Spec Design

Spec Design & Issue Creation

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

Workflow Overview

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:

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

1. Tell user: "Spec written to .context/specs/<name>.md - please review" 2. Open: open .context/specs/<name>.md 3. 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:

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:

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

## 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

Interview Guide

Detailed questions for spec discovery. Use AskUserQuestion tool, 2-4 questions at a time.

1. Problem & Product Mindset (Start Here)

Anchor the entire conversation on the user problem:

• What user problem does this solve?
• Who experiences this problem? How painful is it?
• What happens if we don't solve this?
• What are current workarounds? Why insufficient?

Reference this problem throughout the interview.

2. Goals & Scope (YAGNI Focus)

• What does success look like?
• What's explicitly OUT of scope?
• YAGNI Challenge: "Are we building only what's needed NOW, or anticipating speculative futures?"
• If user proposes future-proofing: "Does this add complexity? Simpler approach?"
• Allow future-proofing ONLY if it maintains simplicity

3. Technical Deep-Dive

Technology Choices (Boring Tech Principle)

• What existing systems/code does this touch?
• Introducing any NEW technology/framework/pattern?
• If yes: "Why not existing solutions? What does new tech give us?"
• Challenge trendy tech: "Is this proven and stable?"

Architecture

• Data model changes needed?
• APIs (internal/external) involved?
• Performance considerations?
• Security implications?

Essential vs Incidental Complexity

For each proposed abstraction/pattern:

• "Is this essential to solve the problem, or complexity we're choosing?"
• "What's the simplest version that solves the core problem?"
• Document which complexity is must-have vs nice-to-have

4. Simplicity Check (Kernighan's Law)

• "Is there a simpler way to do this?"
• "Could a developer unfamiliar with the codebase understand this?"
• "Are we being clever when we could be clear?"

5. Best Practices Challenge

If user suggests a pattern that seems like blind adoption:

• "Why this pattern specifically for OUR context?"
• "What trade-offs are we accepting?"

Only challenge if it seems like "best practice" without contextual reasoning.

6. Edge Cases & Risks

• What could go wrong?
• What's the blast radius if this fails?
• What assumptions are we making?
• Dependencies on other teams/systems?

7. UX/UI (if applicable)

• What's the user flow?
• Error states and handling?
• What feedback does the user need?

8. Acceptance Criteria

• How do we know it's done?
• What tests prove it works?

Interview Style

• Ask 2-4 questions at a time
• Go deep on answers - follow up on interesting points
• Challenge assumptions respectfully
• Reference the user problem throughout
• Continue until enough detail for complete spec

Spec Template

Write this to /tmp/spec-design.md, filling in all sections.

# [Feature Name]

## Problem Statement
[Clear description of the USER PROBLEM - not the solution]

## Goals
- [Goal 1]
- [Goal 2]

## Non-Goals (YAGNI)
- [Explicitly out of scope item 1]
- [Explicitly out of scope item 2]

## Technical Design

### Approach
[Architecture, data model, APIs, etc.]

### Technology Choices
[What we're using and WHY - especially if new tech is introduced]

### Simplicity Check
[Rationale for why this is the simplest viable approach]
[What simpler alternatives were considered and why they don't work]

## Complexity Analysis

### Essential Complexity (Must Handle)
- [Inherent difficulty 1]
- [Inherent difficulty 2]

### Incidental Complexity (Choosing to Add)
- [Optional complexity 1]: [justification]
- [Optional complexity 2]: [justification]

## User Experience
[Flows, UI considerations, error handling - if applicable]

## Refactoring Opportunities
[Existing code to clean up before/during this work]
[Technical debt this feature could address]

## Automation Considerations
- CI/CD changes needed: [list]
- New tests required: [unit, integration, e2e]
- Monitoring/alerting: [what to add]

## Known Risks & Mitigations

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| [Risk 1] | [H/M/L] | [H/M/L] | [How we'll handle it] |
| [Risk 2] | [H/M/L] | [H/M/L] | [How we'll handle it] |

## Sub-tasks & Dependencies

graph TD A[Sub-issue 1: Title] --> B[Sub-issue 2: Title] A --> C[Sub-issue 3: Title] B --> D[Sub-issue 4: Title] C --> D

| # | Sub-issue | Depends On | Summary |
|---|-----------|------------|---------|
| 1 | [Title]   | -          | [Brief] |
| 2 | [Title]   | 1          | [Brief] |
| 3 | [Title]   | 1          | [Brief] |
| 4 | [Title]   | 2, 3       | [Brief] |

## Acceptance Criteria
- [ ] [Criterion 1]
- [ ] [Criterion 2]

Sub-Issue Body Template

Each sub-issue should contain:

## Context
[What this is part of and why - reference user problem]

## Scope
[What this sub-issue covers - smallest logical unit]

## Depends On
[List of sub-issue dependencies or "None - can start immediately"]

## Acceptance Criteria
- [ ] [Specific, verifiable criteria]