| name | joycraft-research |
| description | Invoked by design/decompose or the human directly — produce objective codebase research by isolating question generation from fact-gathering |
Research Codebase for a Feature
You are producing objective codebase research to inform a future spec or implementation. The key insight: the researching agent must never see the brief or ticket — only research questions. This prevents opinions from contaminating the facts.
Guard clause: If the user doesn't provide a brief path or inline description, ask:
"What feature or change are you researching? Provide a brief path or describe it."
Step 0: Retrieve Before You Reason (PROTOCOL)
Before generating a single research question, run a bounded grep-first retrieval pass over the durable knowledge layer — a capped lookup, not a reading assignment:
- Derive 3-6 search terms from the brief's (or inline description's) key concepts.
- Grep, in priority order:
docs/context/decision-log.md, docs/context/shipped.md, docs/discoveries/, remaining docs/context/*.md.
- Read at most 5 files/rows total; if a term returns dozens of hits, read only the newest within the cap and say the result was truncated.
- Empty or missing knowledge layer (fresh project): report "nothing to retrieve" in one line and proceed — never block.
Output contract: the research document MUST include a "Prior knowledge reused" section — a list citing each reused doc + row date/heading, or the explicit line "retrieval ran (terms: …), nothing relevant found."
Contradictions: if a retrieved decision or discovery contradicts the brief's direction, surface it explicitly in your handoff — never silently pick a side.
Phase 1: Generate Research Questions
Read the brief and identify which zones of the codebase are relevant. Generate 5-10 research questions that are:
- Objective and fact-seeking — "How does X work?" not "How should we build X?"
- Specific to the codebase
- Answerable by reading code
Output path:
- If a brief exists at
docs/features/<slug>/brief.md, write to docs/features/<slug>/research.md (per-feature layout).
- If no brief exists (inline description only), write to
docs/research/YYYY-MM-DD-feature-name.md (flat layout).
Write the questions to docs/features/<slug>/.questions-tmp.md. Do NOT include any content from the brief.
Phase 2: Spawn Research Subagent
Spawn a subagent to perform the research. Pass ONLY the research questions — never the brief.
Subagent prompt:
You are researching a codebase to answer specific questions. You have NO context about why these questions are being asked.
RULES:
- Answer each question with FACTS ONLY: file paths, function signatures, data flows, patterns, dependencies
- Do NOT recommend, suggest, or opine
- Do NOT speculate about what should be built
- If a question cannot be answered, say "No existing code found for this"
- Search the codebase and read files thoroughly
- Include code snippets only when essential evidence
QUESTIONS:
[INSERT_QUESTIONS_HERE]
OUTPUT FORMAT:
# Codebase Research
**Date:** [today]
**Questions answered:** [N/total]
---
## Q1: [question]
[Facts only]
## Q2: [question]
[Facts only]
Phase 3: Write the Research Document
Write the subagent's response to docs/features/<slug>/research.md, adding a "Prior knowledge reused" section at the top from Step 0's retrieval pass (or the line "retrieval ran (terms: …), nothing relevant found"). Delete the temporary questions file.
Update the Feature Brief
After writing the research document, update the parent brief with a back-reference:
- Read
docs/features/<slug>/brief.md
- In the header blockquote (the
> lines at the top), add or update:
> **Research:** docs/features/<slug>/research.md
- If a
> **Research:** line already exists, replace it — do NOT add a duplicate
- Write the brief back
Present:
Research complete: docs/features/<slug>/research.md
This document contains objective facts — no opinions or recommendations.
Recommended next step:
- $joycraft-design — translate research findings into architectural decisions before building
If the scope is simple (< 5 files, well-understood area, no architectural decisions):
- $joycraft-decompose — skip design and break directly into atomic specs
Other options:
- $joycraft-new-feature — formalize into a full Feature Brief first
- Read the research and add corrections manually
Phase 4: Reconcile Brief with Findings
You've just written docs/features/<slug>/research.md. Before hand-off, the parent brief at docs/features/<slug>/brief.md may now disagree with what you discovered. Re-read it and check each of these sections:
| Brief section | What to look for |
|---|
| Vision | Did your findings refine or contradict the framing? |
| Hard Constraints | Are any constraints now obsolete, missing, or refined? |
| Out of Scope | Did your findings push something in or out of scope? |
| Decomposition | Are spec counts, names, or dependencies still accurate? |
| Test Strategy | Do your findings change what or how to test? |
| Success Criteria | Are the criteria still observable and still match the goal? |
For each section, choose one:
- Edit in place — small, mechanical updates: line-number corrections, clarifications, additions consistent with brief intent. No user approval needed.
- Diff + stop — non-trivial changes: counts flipping, decomposition restructure, scope changes, contradiction with original brief intent. Present a diff of the proposed change, STOP, and wait for user approval before continuing.
If you make changes, note them at the bottom of research.md under a "Brief updates" subsection. If the brief is already in sync, note: "Reconciliation checked, no changes required." If no parent brief exists (feature was described inline), note that and skip this step.
Why this step exists: the silent-drift gap. Without reconciliation, the brief and downstream artifacts diverge — and later decomposition is sized against the stale brief. This feature ("single-source-skills") hit exactly this: brief said "11 clean / 9 dirty" until the research re-audit forced a re-decomposition. Don't let it happen again.
