Research output types

Research Question

What are the possible output types from a research item, and how should each type be handled, stored, and acted upon?

Findings

Executive Summary

The research item output taxonomy consists of exactly five types — skill, tool, agent, knowledge, and backlog-item — defined consistently across AGENTS.md, Research/README.md, and Research/_template.md. The taxonomy is sufficient: no additional types such as "dataset" or "prompt template" are warranted because they fold cleanly into existing types. The handling procedures for tool, knowledge, and backlog-item are well-defined and demonstrated by the completed corpus; the procedures for skill (creating a directory and SKILL.md in the external Skills repo) and agent (no storage convention exists) are under-documented and have not been fully acted upon in any completed item.

Key Findings

1. Five output types are enumerated consistently across three authoritative locations (AGENTS.md, Research/README.md, Research/_template.md): skill, tool, agent, knowledge, and backlog-item, with no discrepancies between the three sources.
2. tool outputs are stored in src/ and have a documented 6-step handling procedure in AGENTS.md: create the Python file, write tests, register in the CLI, optionally write an ADR, and update BACKLOG.md and PROGRESS.md.
3. skill outputs are stored as named directories containing a SKILL.md file in davidamitchell/Skills; the repository currently has 13 skill directories, and the submodule sync to .github/skills/ and .claude/skills/ is automated via sync-skills.yml.
4. The skill output type is under-acted in the corpus: two completed items declare it in their front-matter, but neither contains a link to a newly created skill directory in davidamitchell/Skills, indicating the handling step has not been completed.
5. The agent output type has no documented storage location or handling procedure beyond its one-line definition in AGENTS.md; no completed research item has used this output type in 26 completed items.
6. backlog-item outputs spawn numbered W-XXXX entries in BACKLOG.md and are the second most common output type, appearing in 13 of 26 completed items; the handling convention (append entry, assign number, link from ## Output) is well-understood and consistently applied.
7. No additional output types are warranted: "dataset" folds into tool or knowledge; "prompt template" folds into skill or agent; the five-type taxonomy has been stable since the repository's founding with no gaps requiring extension over 26 completed items.
8. The output: front-matter field (array, e.g. output: [knowledge, backlog-item]) makes output types machine-readable; the ## Output section provides the human-readable description, type, and links — both fields are required for a complete output record.

Assumptions

• Assumption: "prompt template" outputs do not require a separate output type. Justification: Prompt templates consumed from the Skills submodule are skill outputs; standalone prompt files like research-prompt.md are agent outputs; the distinction is one of deployment mechanism rather than fundamental type.
• Assumption: An agent output most plausibly maps to a prompt file at the repo root or a configuration in .github/. Justification: research-prompt.md and .github/mcp.json are the only agent-like configurations in the repository; no other format is in use and no convention points elsewhere.

Analysis

Risks, Gaps, and Uncertainties

• Gap: The agent output type has no storage convention. If a research item produces an agent configuration, there is no documented guidance on where to store it or what format it should take. This gap is not urgent (no completed item has triggered it) but will become a problem when the first agent-type output is produced.
• Gap: The skill handling procedure is under-documented in AGENTS.md. The single sentence "add it to the Skills repo first" does not explain the directory/SKILL.md structure, the authentication method for committing to an external repository, or how to link the resulting skill from the research item's ## Output section.
• Uncertainty: The knowledge type is simultaneously implicit (every item is a knowledge artifact) and explicit (an ADR or README update was also produced). This dual meaning has not caused problems in practice, but it creates ambiguity about what an agent should do when a research item produces a knowledge output — is action required beyond completing the item, or is the item completion itself sufficient?
• Uncertainty: The wiki publish pipeline constitutes an additional, implicit storage location for knowledge outputs that is not described in the output type taxonomy. The taxonomy does not distinguish between knowledge that lives only in Research/completed/ and knowledge that is also published to the wiki.

Open Questions

• Should AGENTS.md document a handling procedure for skill outputs with the same specificity as it documents tool outputs — including the directory structure, SKILL.md format, and how to commit to the external Skills repo?
• Should the agent output type have a designated storage location (e.g., an agents/ directory at the repo root) and a documented handling procedure?
• Should the knowledge type be clarified to distinguish "the completed item itself is the knowledge artifact" from "a separate ADR, README update, or wiki note was also produced"?

sources

• [x] davidamitchell/Skills repo — existing skill categories
• [x] AGENTS.md — current output type list