Design discussion before decomposition — produce a ~200-line design artifact for human review, catching wrong assumptions before they propagate into specs
You are producing a design discussion document for a feature. This sits between research and decomposition — it captures your understanding so the human can catch wrong assumptions before specs are written.
Guard clause: If no brief path is provided and no brief exists in docs/briefs/, say:
"No feature brief found. Run $joycraft-new-feature first to create one, or provide the path to your brief."
Then stop.
Read the feature brief at the path the user provides. If the user also provides a research document path, read that too.
Spawn concurrent subagent threads to explore the codebase for patterns relevant to the brief. Focus on:
Each subagent should search the codebase and read files to gather file paths, function signatures, and code snippets.
Create docs/designs/ directory if it doesn't exist. Write to docs/designs/YYYY-MM-DD-feature-name.md.
The document has exactly five sections:
What exists today in the codebase. Include file paths, function signatures, data flows. Be specific.
What the codebase should look like when this feature is complete.
Existing patterns in the codebase that this feature should match. Include code snippets and file:line references.
Decisions made with rationale. Format: Decision, Rationale, Alternative rejected.
Things where multiple valid approaches exist. Each question MUST present 2-3 concrete options with pros and cons.
Present the design document. Say:
Design discussion written to docs/designs/YYYY-MM-DD-feature-name.md
Please review. Specifically:
1. Are the patterns in Section 3 right?
2. Do you agree with the resolved decisions?
3. Pick an option for each open question.
Reply with your feedback. I will NOT proceed to decomposition until you have reviewed and approved.
CRITICAL: Do NOT proceed to $joycraft-decompose or generate specs. Wait for human review.
$joycraft-decompose with this brief to generate atomic specs."