Spec Design & Issue Creation

Conduct principle-driven interviews to create comprehensive specs, then create GitHub issue hierarchies.

Workflow Overview

code

Phase 1: Discovery Interview  → Read references/interview-guide.md
Phase 2: Principles Summary   → Confirm decisions with user
Phase 3: Write Spec          → Read references/spec-template.md
Phase 4: Review Spec         → User reviews .context/specs/<issue>.md
Phase 5: Create Issues       → Use gh-issues skill

Phase 1: Discovery Interview

If no initial context: Ask user what they want to spec out.

Interview approach:

•Use AskUserQuestion tool throughout
•Ask 2-4 questions at a time
•Go deep on answers, follow up on interesting points
•Challenge assumptions respectfully
•Reference the user problem throughout

Core principles to weave in:

•YAGNI: Build only what's needed NOW
•Simplicity: Simplest viable approach
•Boring Tech: Proven over trendy
•User Problem: Every decision traces back to it

→ Read references/interview-guide.md for detailed questions.

RFC Detection

Watch for signals needing broader review:

•Breaking API changes
•Significant database migrations
•New architectural patterns
•Cross-team dependencies

If detected: "This seems significant. Should we generate an RFC template instead?"

Phase 2: Principles Summary

Before writing spec, confirm with user:

code

Before I write the spec, let's confirm:

✓ USER PROBLEM: [one-line summary]
✓ YAGNI - NOT building: [out of scope items]
✓ SIMPLICITY: [approach and why it's simplest]
✓ TECHNOLOGY: [choices with reasons]
✓ COMPLEXITY:
  - Essential: [must have]
  - Incidental: [choosing to add + justification]
✓ RISKS: [risk → mitigation]

Does this capture our decisions?
Options: ["Yes, write the spec", "Let me clarify"]

Phase 3: Write Spec

→ Read references/spec-template.md for the template.

Write spec to .context/specs/<feature-name>.md (or <issue-number>.md if known).

Sub-task splitting guidelines:

•Each sub-issue = SMALLEST LOGICAL UNIT
•INDEPENDENT: can ship without other sub-issues
•VERIFIABLE: clear "done" state, testable in isolation
•Consider: data layer → API layer → UI layer
•Consider: core functionality → edge cases → polish

Phase 4: Review Spec

•Tell user: "Spec written to .context/specs/<name>.md - please review"
•Open: open .context/specs/<name>.md
•
Ask: "Ready to create GitHub issues?"
- •Options: ["Yes, create issues", "I'll edit first", "Cancel"]

If user edits, re-read the file before proceeding.

Phase 5: Create Issues

Ask about assignment:

•Options: ["Assign to me", "Leave unassigned"]

Create main issue:

bash

gh issue create --title "[Feature Name]" --body "$(cat .context/specs/<name>.md)"

Create sub-issues: Use gh-issues skill (see references/hierarchy.md).

For each sub-issue, confirm with user:

code


Proposed sub-issue [1/N]:
Title: [title]
Body: [context, scope, depends on, acceptance criteria]

Create this?
Options: ["Yes", "Skip", "Modify"]

Use parallel subagents for independent sub-issues.

Phase 6: Summary

code


## Created Issues

Main: #[number] - [title]
├── #[sub1] - [title] (ready)
├── #[sub2] - [title] (blocked by #sub1)
└── #[sub3] - [title] (blocked by #sub1)

Dependency order:

1. #[sub1] - start now
2. #[sub2], #[sub3] - after #sub1

Run `/load-issue [number]` to start working.

Notes

•Use current repository
•Use gh-issues skill for sub-issue creation (native GitHub sub-issues)
•Include enough context in each sub-issue for independent agent work
•Keep USER PROBLEM central throughout