joycraft-research
Skill15 starsChanged 54 days agoMITView on GitHub
Invoked by design/decompose or the human directly — produce objective codebase research by isolating question generation from fact-gathering
In this repository70 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- joycraft-add-contextSkill
- joycraft-add-factSkill
- joycraft-bugfixSkill
- joycraft-collaborative-setupSkill
- joycraft-decideSkill
- joycraft-decomposeSkill
- joycraft-designSkill
- joycraft-gather-contextSkill
- joycraft-hardenSkill
- joycraft-implement-featureSkill
- joycraft-implement-level5Skill
- joycraft-implementSkill
- joycraft-interviewSkill
- joycraft-lockdownSkill
- joycraft-new-featureSkill
- joycraft-optimizeSkill
- joycraft-session-endSkill
- joycraft-setupSkill
- joycraft-spec-doneSkill
- joycraft-tuneSkill
- joycraft-verifySkill
- release-docs-syncSkill
- joycraft-add-contextSkill
- joycraft-add-factSkill
- joycraft-bugfixSkill
- joycraft-collaborative-setupSkill
- joycraft-decideSkill
- joycraft-decomposeSkill
- joycraft-designSkill
- joycraft-gather-contextSkill
- joycraft-hardenSkill
- joycraft-implement-featureSkill
- joycraft-implement-level5Skill
- joycraft-implementSkill
- joycraft-interviewSkill
- joycraft-lockdownSkill
- joycraft-new-featureSkill
- joycraft-optimizeSkill
- joycraft-researchSkill
- joycraft-session-endSkill
- joycraft-setupSkill
- joycraft-spec-doneSkill
- joycraft-tuneSkill
- joycraft-verifySkill
- release-docs-syncSkill
- joycraft-add-contextSkill
- joycraft-add-factSkill
- joycraft-bugfixSkill
- joycraft-collaborative-setupSkill
- joycraft-decideSkill
- joycraft-decomposeSkill
- joycraft-designSkill
- joycraft-gather-contextSkill
- joycraft-hardenSkill
- joycraft-implement-featureSkill
- joycraft-implement-level5Skill
- joycraft-implementSkill
- joycraft-interviewSkill
- The first 60 shown.
The file
Show its rules and text
We split this skill into the rules it gives an agent
19 rules. About 0 are common, 8 are distinctive, and 11 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
11
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
Guard clause: If the user doesn't provide a brief path or inline description, ask: "What feature or change are you researching?
- Distinctive: line 17
Before generating a single research question, run a bounded grep-first retrieval pass over the durable knowledge layer — a capped lookup, …
- Distinctive: line 21
Read at most 5 files/rows total.
- Distinctive: line 26
Contradictions: if a retrieved decision or discovery contradicts the brief's direction, surface it explicitly in your handoff — never …
- Distinctive: line 32
Read the brief and identify which zones of the codebase are relevant.
- Very specific: line 38
If a brief exists at docs/features/<slug>/brief.md, write to docs/features/<slug>/research.md (per-feature layout).
- Very specific: line 39
If no brief exists (inline description only), write to docs/research/YYYY-MM-DD-feature-name.md (flat layout).
- Very specific: line 41
Write the questions to docs/features/<slug>/.questions-tmp.md.
- Very specific: line 82
Write the subagent's response to docs/features/<slug>/research.md, adding a "Prior knowledge reused" section at the top from Step 0's …
- Distinctive: line 86
After writing the research document, update the parent brief with a back-reference:
- Very specific: line 90
If a > Research: line already exists, replace it — do NOT add a duplicate
- Distinctive: line 91
Write the brief back
- Very specific: line 95
If the artifact contains any open question, or any load-bearing claim anchored ≤50, invoke $joycraft-decide on it NOW — before presenting.
- Very specific: line 100
If the human already answered them in conversation, that counts as termination: stamp the decisions: frontmatter and proceed — no dossier …
- Very specific: line 110
Read docs/templates/REVIEW_GATE_TEMPLATE.html.
- Very specific: line 114
Write it to docs/features/<slug>/research.html (committed later — the path is already linguist-generated, so PRs collapse it).
- Very specific: line 123
When the readout carries two or more questions for the human, the render is an interactive checkpoint instead: build it per …
- Distinctive: line 143
Keep it inline here on purpose: inline placement is load-bearing — referenced docs get partially read or skipped at output time (Anthropic …
- Very specific: line 184
If you make changes, note them at the bottom of research.md under a "Brief updates" subsection.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
At skill entry, run node docs/.joycraft/check.mjs check --json --session <session-id> once, reusing JOYCRAFT_SESSION_ID if supplied or one ID chosen for this conversation. If the checker is missing or fails, continue the requested skill quietly without retrying setup. Offer updates only for display: true; current, postponed, off, and unknown stay quiet. If automaticUpdate is present, finish this skill, then run its exact command once from the project root: the candidate must verify every safety gate before applying. Other updates require approval. After an offer or automatic attempt, record it with node docs/.joycraft/check.mjs acknowledge <available-version> --session <session-id>. Apply updates only at this workflow boundary; after success, reinvoke the skill or restart the session to load changed instructions.
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/, remainingdocs/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 todocs/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
Decide first — the pre-presentation rule
If the artifact contains any open question, or any load-bearing claim anchored
≤50, invoke $joycraft-decide on it NOW — before presenting. The Block Rule
(docs/context/anchors.md) fires pre-approval, every time; presenting
an artifact with open questions asks the human to approve an incomplete
artifact.
If the human already answered them in conversation, that counts as termination:
stamp the decisions: frontmatter and proceed — no dossier required. Zero open
questions and no ≤50 claims → the gate passes silently.
Render and open the research
docs/features/<slug>/research.md is written first and stays canonical —
agents read the md, never the HTML. The HTML is a render of it and never invents
content.
- Read
docs/templates/REVIEW_GATE_TEMPLATE.html. Fill ONLY the<!-- SLOT:name — … -->regions per each slot's inline guidance; the template's structure, class names, CSS, and theme script stay byte-identical — never generate freeform gate HTML. - Write it to
docs/features/<slug>/research.html(committed later — the path is already linguist-generated, so PRs collapse it). Re-running the gate overwrites the same file; the md is the record. - Open it before asking anything:
open <path>on darwin,xdg-open <path>otherwise. If both fail, print the absolute path and continue — headless, CI, and isolated mode are a no-op here, never a failure. - Offer — don't push — an optional extra render: "I can also publish this research as a hosted artifact for a shareable link." Only publish if the human says yes; the local file remains the canonical render. If declined, no retry.
- When the readout carries two or more questions for the human, the render is
an interactive checkpoint instead: build it per
docs/templates/reference/interactive-checkpoint.mdand read the answers back before stamping. The local file stays the canonical render.
At this gate, your chat message is EXACTLY this template — nothing outside it. The content lives in the artifact, not the chat. Findings go in the research document — never paste them into chat.
**Research complete: <the finding that changes what we build, one line>**
Artifact: <absolute path> (opened) · canonical: docs/features/<slug>/research.md
Decisions needed: <N> — <ids/titles, comma-separated>
<one-line summary per decision, only if N ≤ 4>
Next: <the single action you want from the human>
Ten lines maximum. If you are about to write an eleventh line, the content
belongs in the artifact — move it there.Keep it inline here on purpose: inline placement is load-bearing — referenced docs get partially read or skipped at output time (Anthropic skill-authoring guidance; observed live 2026-07-29).
The block below is the artifact's content, not your chat message.
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 manuallyPhase 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.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

