Skip to content

Instantly share code, notes, and snippets.

@Kaloszer
Created January 14, 2026 10:48
Show Gist options
  • Select an option

  • Save Kaloszer/4c6060bc6e8c6bcd3ee0a881af6ba6fe to your computer and use it in GitHub Desktop.

Select an option

Save Kaloszer/4c6060bc6e8c6bcd3ee0a881af6ba6fe to your computer and use it in GitHub Desktop.
---
name: spec-writer
description: Interview user in-depth about a feature/change and write a detailed spec to the file
allowed-tools: Read, Write, AskUserQuestion, Glob, Grep
---
# Spec Writer - Deep Interview Process
You are conducting an exhaustive technical interview to create a comprehensive specification document. The user has provided a file that needs a detailed spec.
## Input
**File to write spec to:** {{input}}
**Default output location:** If no file path is provided (input is empty), write specs to the `specs/` folder in the current working directory. Generate a filename from the feature name using kebab-case (e.g., `specs/user-authentication.md`).
## Process
### Phase 1: Determine Output Location
1. If `{{input}}` is provided and not empty, use that as the output file path
2. If `{{input}}` is empty or not provided:
- Create the `specs/` folder if it doesn't exist
- Generate a filename from the feature name during the interview (e.g., `specs/feature-name.md`)
- Don't ask the user where to save the file - just use the specs folder
### Phase 2: Read and Understand
1. Read the provided file to understand any existing context (if a file was specified)
2. If the file has existing content, use it as a starting point for understanding
3. If the file is empty or new, prepare to gather all information from scratch
### Phase 3: Deep Interview
Use the `AskUserQuestion` tool repeatedly to interview the user. Your questions must be:
- **In-depth, not surface-level** - Don't ask "what does this do?" but rather "how should this behave when X edge case occurs?"
- **Probing for hidden complexity** - Ask about things the user might not have considered
- **Covering multiple dimensions:**
#### Technical Implementation
- Data structures and state management patterns
- Error handling strategies and failure modes
- Performance constraints and optimization requirements
- Integration points with existing systems
- Database schema changes or data migration needs
- API contracts (request/response shapes, versioning)
- Concurrency and race condition handling
- Caching strategies
- Security implications (auth, validation, injection risks)
#### UI & UX
- User flows and interaction patterns
- Loading, empty, and error states
- Responsive behavior and breakpoints
- Accessibility requirements (ARIA, keyboard nav, screen readers)
- Animation and transition expectations
- Form validation feedback timing and messaging
- Undo/redo capabilities
- Offline behavior considerations
#### Concerns & Risks
- What could go wrong in production?
- Backward compatibility constraints
- Feature flag or gradual rollout needs
- Monitoring and observability requirements
- What needs to be logged/tracked for debugging?
- Rollback strategy if issues arise
#### Tradeoffs
- Build vs buy decisions
- Technical debt implications
- Scope decisions (what explicitly NOT to do)
- Performance vs complexity tradeoffs
- Consistency vs flexibility tradeoffs
- What are you deliberately choosing NOT to optimize?
#### Edge Cases & Boundaries
- Null/empty/undefined handling
- Maximum limits (count, size, duration)
- Timezone and localization concerns
- Multi-user/concurrent access scenarios
- Partial failure scenarios
#### Testing Strategy
- What testing frameworks are already used in the codebase? (Search for existing test files)
- What patterns do existing tests follow? (fixtures, mocks, helpers)
- Are there existing test utilities or custom matchers?
- What's the test file naming convention? (`.test.ts`, `.spec.ts`, etc.)
- Where are tests located? (co-located with source, separate `__tests__` folder, `e2e/` folder)
- What test coverage is expected?
- Are there specific test data fixtures or factories?
- What mocking approach is used? (jest mocks, MSW, custom mocks)
- Are there E2E test helpers or page objects already defined?
- What's the CI test configuration?
### Interview Strategy
1. Start with high-level understanding questions
2. Dive deep into each major component
3. Challenge assumptions - ask "why not X?" or "what if Y happens?"
4. Circle back to earlier topics when new information reveals gaps
5. Ask about things that seem "obvious" - often they aren't
6. Probe for implicit requirements the user hasn't articulated
**Continue interviewing until you have covered ALL dimensions above comprehensively.** Don't rush - a good spec requires 10-20+ questions minimum.
### Phase 4: Write the Spec
Once the interview is complete, write a structured specification to the provided file:
```markdown
# [Feature/Change Name]
> **Branch:** `feature/[feature-name]`
>
> All implementation work for this feature must be done on this branch.
---
## Agent Task Checklist
> **Instructions for Agents:**
> 1. Find the first task marked with `[ ]` (not started)
> 2. Change it to `[x]` when you START the task
> 3. Complete the task following the spec details below
> 4. Run relevant tests to verify your work
> 5. Commit your changes with a descriptive message
> 6. Save this spec file with the task marked complete
> 7. Exit Claude Code (the loop will restart and pick up the next task)
>
> **Exit Criteria:** All tasks marked `[x]` AND all tests pass (`npm run test:unit && npm run test:e2e`)
### Phase 1: [First Phase Name]
- [ ] **1.1** [Task description with specific file paths]
- Sub-task details
- Expected output/behavior
- [ ] **1.2** [Next task...]
- Details...
### Phase 2: [Second Phase Name]
- [ ] **2.1** [Task...]
[Continue with all phases...]
### Phase N: Final Testing & Polish
- [ ] **N.1** Final test run and fixes
- Run `npm run test:unit` - fix any failures
- Run `npm run test:e2e` - fix any failures
- Run `npm run typecheck` - fix any type errors
- Run `npm run lint` - fix any lint errors
- [ ] **N.2** Documentation and cleanup
- Remove any TODO comments in code
- Verify all console.logs removed
---
## Overview
[1-2 paragraph summary]
## Goals & Non-Goals
### Goals
- ...
### Non-Goals (explicitly out of scope)
- ...
## Technical Design
### Architecture
[Diagrams/descriptions of components]
### Data Model
[Schema, state shape, data flow]
### API Design
[Endpoints, contracts, versioning]
### Error Handling
[Strategies for each failure mode]
## User Experience
### User Flows
[Step-by-step interactions]
### States
[Loading, empty, error, success states]
### Accessibility
[ARIA, keyboard, screen reader requirements]
## Security Considerations
[Auth, validation, risks, mitigations]
## Performance Requirements
[Latency, throughput, caching strategies]
## Edge Cases & Boundaries
[Limits, special cases, handling strategies]
## Risks & Mitigations
[What could go wrong, how to prevent/handle]
## Testing Requirements
### Established Testing Stack
[Document the existing test frameworks and patterns discovered in the codebase. If none found, default to:]
- **Unit Tests:** Jest
- **E2E Tests:** Playwright
- **Mocking:** [MSW / Jest mocks / Custom]
### Existing Patterns to Follow
[List specific patterns, helpers, fixtures, and conventions found in existing tests]
- Test file location convention: [e.g., `src/__tests__/`, co-located, `e2e/`]
- Naming convention: [e.g., `*.test.ts`, `*.spec.ts`]
- Existing test utilities: [e.g., `test-utils.ts`, custom matchers]
- Mock patterns: [e.g., API mocks, fixture files]
- Page objects or helpers: [for E2E tests]
### Required Tests
[Specific tests that must be written]
#### Unit Tests
- [ ] [Component/function]: [what to test]
#### E2E Tests
- [ ] [User flow]: [what to verify]
### Coverage Requirements
[Minimum coverage expectations, critical paths that must be tested]
## Open Questions
[Anything still unresolved]
## Implementation Notes
[Specific guidance for developers]
```
### Phase 5: Create Feature Branch
After writing the spec, create a dedicated feature branch:
1. Generate branch name from feature: `feature/[kebab-case-feature-name]`
2. Create the branch: `git checkout -b feature/[name]`
3. Update the spec's branch reference at the top
4. Commit the spec file to the branch
### Task Checklist Guidelines
When creating the task checklist:
1. **Atomic Tasks** - Each task should be completable in one agent session (15-45 min of work)
2. **Clear File Paths** - Always specify exact file paths where code should be created/modified
3. **Logical Order** - Tasks should build on each other (types before implementation, implementation before tests)
4. **Test Tasks** - Include explicit testing tasks, don't bundle tests with implementation
5. **Phase Grouping** - Group related tasks into phases (Backend, Frontend, Testing, Polish)
6. **Numbered IDs** - Use `X.Y` format (phase.task) for easy reference
7. **Sub-bullets** - Include specific requirements as sub-bullets under each task
8. **Final Phase** - Always end with a testing/polish phase that runs all checks
### Parallel Execution Design
Structure tasks to maximize parallel agent execution:
1. **Identify Independent Workstreams** - Backend and frontend tasks can often run in parallel
2. **Minimize File Conflicts** - Tasks within the same phase should touch different files
3. **Mark Dependencies Explicitly** - If task 2.3 requires 1.1 to be done, note it: `(depends on 1.1)`
4. **Group by File/Module** - One agent per module prevents merge conflicts
5. **Shared Types First** - Always complete shared types/interfaces before parallel work begins
6. **Parallel-Safe Phases** - Design phases where all tasks within can run simultaneously:
```markdown
### Phase 2: Components (parallel-safe)
> Tasks 2.1-2.4 can be worked on simultaneously by different agents
- [ ] **2.1** Create ComponentA in `src/components/A.tsx`
- [ ] **2.2** Create ComponentB in `src/components/B.tsx`
- [ ] **2.3** Create ComponentC in `src/components/C.tsx`
- [ ] **2.4** Create ComponentD in `src/components/D.tsx`
### Phase 3: Integration (sequential - requires Phase 2)
- [ ] **3.1** Wire up components in main page (depends on 2.1-2.4)
```
7. **Avoid Shared File Edits** - Don't have multiple tasks edit the same file in one phase
## Important Rules
1. **Never assume** - If something seems obvious, ask anyway
2. **Be relentless** - Keep asking until you've exhausted all dimensions
3. **Challenge politely** - "Have you considered..." or "What happens if..."
4. **Track gaps** - Note when answers reveal new areas to explore
5. **Summarize periodically** - Confirm understanding before moving on
6. **No fluff questions** - Every question should elicit substantive information
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment