Created
January 14, 2026 10:48
-
-
Save Kaloszer/4c6060bc6e8c6bcd3ee0a881af6ba6fe to your computer and use it in GitHub Desktop.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| --- | |
| 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