pavel-molyanov/tech-spec-planning

Tech Spec Planning

Create technical specification through code research, adaptive clarification, and multi-validator review.

Input: work/{feature}/user-spec.md + Project Knowledge Output: work/{feature}/tech-spec.md (approved) Language: Technical documentation in English, communication in Russian

Phase 1: Load Context

1. Ask user for feature name if not provided. Check work/{feature}/ exists, create if needed.

2. Read work/{feature}/user-spec.md. If missing — ask user to describe the task or create user-spec first. Extract size: S|M|L from user-spec frontmatter — it determines testing strategy depth in tech-spec.

3. Read all files in .claude/skills/project-knowledge/references/ (project.md, architecture.md, patterns.md, deployment.md, ux-guidelines.md, and any custom domain files). Missing files are fine — not all projects have all guides.

4. user-spec.md is the single input source — all information from interview.yml and code research is already consolidated there.

Checkpoint:

• [ ] Feature folder exists
• [ ] user-spec.md read, size extracted
• [ ] Project Knowledge read

Phase 2: Code Research

Launch code-researcher subagent (Task tool, opus) with feature path and user-spec path. The agent reads existing code-research.md (from user-spec phase if available) and deepens analysis for implementation.

After subagent completes — read {feature_path}/code-research.md. Use in Phase 3 clarification and Phase 4 spec writing.

If during later phases a gap is discovered — launch code-researcher again with the specific question.

Checkpoint:

• [ ] code-research.md created/updated with implementation-level analysis
• [ ] Research file read by orchestrator

Phase 3: Clarification (Adaptive)

Analyze if additional information is needed based on user-spec and code research.

• Ask technical questions if gaps exist. No limit on question count — ask as many as needed.
• Focus: technical constraints, integration points, data sources, external dependencies.
• If gaps found in user-spec requirements — discuss with user and update user-spec too (via subagent or directly).
• If requirements are fundamentally unclear — suggest creating user-spec first.

Checkpoint:

• [ ] All technical gaps clarified (or none existed)

Phase 4: Create tech-spec

1. Copy template to feature folder:

   cp ~/.claude/shared/work-templates/tech-spec.md.template work/{feature}/tech-spec.md
   

   Then edit sections one by one using Edit tool. This keeps template structure and examples visible while you work.

2. Fill frontmatter:

   • created: today's date
   • status: draft
   • size: copy from user-spec (S|M|L)
   • branch: dev

3. Fill all template sections. The template defines section structure — follow it directly. In Architecture → Shared Resources: list heavy resources (ML models, DB pools, browser instances, API clients) shared across components. Specify owner (who creates), consumers, instance count. If none — write "None".

   User-spec anchoring: Every decision in the Decisions section must reference a user-spec requirement it serves (e.g., "Supports US-3: push notifications"). If a decision is purely technical (not derived from any user-spec requirement) — mark it [TECHNICAL] with justification. If a decision contradicts or changes a user-spec requirement — document it in the User-Spec Deviations section and mark as [PENDING USER APPROVAL]. All deviations must be documented explicitly — this preserves the user's original intent for review.

4. Fill Implementation Tasks by waves. For each task provide: Description, Skill, Reviewers, Verify-smoke (optional), Verify-user (optional), Files to modify, Files to read. Select skill and reviewers from skills-and-reviewers.md (execution skills catalog, reviewer agents, default mappings).

   For each task, write Verify-smoke: when the task involves:

   • External API integration → curl/httpie command to real endpoint with expected response
   • Library/model initialization → python -c or import check that verifies setup
   • Docker/infrastructure → docker compose build, docker run commands
   • LLM/prompt work → spawn agent with prompt + test question, check response
   • External service API (OpenRouter, Stripe, etc.) → test API call with expected response
   • MCP-verifiable UI/frontend → use Playwright MCP or similar to check rendered page Write Verify-user: when user should check something: UI on localhost, behavior, UX. Omit both if task is purely internal logic covered by unit tests.

   Task brevity rules:

   • Tasks are brief scope descriptions (2-3 sentences). Detailed steps, AC, and TDD anchors are created during task-decomposition phase.
   • Task Description answers WHAT and WHY, not HOW. No step-by-step instructions, no line numbers, no implementation details.
   • All technical decisions belong in the Decisions section, not in task descriptions. If you're writing a decision rationale inside a task — move it to Decisions.

5. The last two waves are always Audit Wave and Final Wave, in that order:

   Audit Wave (always present) — 3 tasks running in parallel, reviewers: none:

   • Code Audit (skill: code-reviewing) — holistic code quality review of all feature code
   • Security Audit (skill: security-auditor) — OWASP Top 10 across all components
   • Test Audit (skill: test-master) — test quality and coverage across all components

   Auditors read all source files from the feature and write reports (analysis only). If issues found — feature-execution lead spawns a fixer agent, auditors become reviewers for the fix.

   Final Wave:

   • QA (skill: pre-deploy-qa) — always present. Acceptance testing: run all tests, verify acceptance criteria from user-spec and tech-spec.
   • Deploy (skill: deploy-pipeline) — only if deploy is needed for this feature.
   • Post-deploy verification (skill: post-deploy-qa) — only if live-environment checks are needed (MCP tools listed in Agent Verification Plan → Tools required). QA is mandatory. Deploy and post-deploy — if applicable.

6. Fill User-Spec Deviations section. For each element in tech-spec that changes, extends, or contradicts user-spec — add an entry with the requirement ID, what user-spec says, what tech-spec does differently, and why. Mark each entry [PENDING USER APPROVAL]. If no deviations — write "None".

7. Task Count Check: if >15 tasks — propose splitting into MVP + Extension phases. Wait for user decision.

8. Git commit: draft(techspec): create tech-spec for {feature}

Checkpoint:

• [ ] tech-spec.md created in work/{feature}/ with all sections
• [ ] Implementation Tasks include Description (2-3 sentences), skill, reviewers for each task
• [ ] No AC or TDD anchors in tasks (those come from task-decomposition phase)
• [ ] Technical decisions are in Decisions section, not in task descriptions
• [ ] Every Decision references a user-spec requirement or is marked [TECHNICAL]
• [ ] User-Spec Deviations section filled (or "None")
• [ ] Final Wave present with QA (mandatory) + Deploy/Post-deploy (if applicable)
• [ ] Task count ≤15 (or user approved larger scope)

Phase 5: Validation

Run 5 validators in parallel

Launch all as subagents, each writes JSON report to logs/techspec/{name}-review.json:

| Validator | Agent | Checks | |-----------|-------|--------| | Mirage detector | skeptic | Non-existent files, APIs, functions, dependencies | | Completeness + adequacy | completeness-validator | Bidirectional traceability, scope creep, overengineering, underengineering, solution depth | | Security | security-auditor | OWASP, input validation, auth, sensitive data | | Testing strategy | test-reviewer | Test plan adequacy for feature size S/M/L | | Template + wave conflicts | tech-spec-validator | All sections filled, frontmatter, format, skills/reviewers, wave conflict detection |

Pass to each validator: work/{feature}/tech-spec.md + work/{feature}/user-spec.md.

Process findings

Read all 5 reports. For each finding:

• Fix if clearly valid (typos, missing sections, structural issues)
• Reject with reasoning if disagree — only for findings unrelated to user-spec alignment

User-spec alignment findings require user decision. When completeness-validator reports gap, scope_creep, overengineering, or shallow_solution — present each finding to the user with your recommendation (fix / keep / adjust). Reason: these findings mean the tech-spec may contradict what the user asked for — only the user can decide whether the deviation is acceptable.

Iterate if needed (up to 3 iterations)

If fixes were made:

1. Apply targeted fixes directly in work/{feature}/tech-spec.md.
2. Git commit: chore(techspec): validation round {N} — {summary of fixes}
3. Re-run validators on updated tech-spec.
4. Repeat up to 3 iterations.

If problems remain after 3 iterations — show user: "Validation didn't pass in 3 iterations. Here's what remains — let's resolve together."

Checkpoint:

• [ ] All 5 validators ran
• [ ] Findings processed (fixed / rejected / discussed)
• [ ] Final tech-spec.md placed in work/{feature}/

Phase 6: User Approval

1. Show user the full tech-spec.md.
2. Show validation summary: iterations count, issues found and resolved.
3. Wait for explicit approval.
4. If user has comments — fix, re-validate, show again.
5. After approval: update status: draft → status: approved in tech-spec frontmatter.
6. Git commit: chore(techspec): approve tech-spec for {feature}
7. Tell user next step: run /decompose-tech-spec to create task files.

Checkpoint:

• [ ] User explicitly approved tech-spec
• [ ] status = approved

Final Check

• [ ] tech-spec.md created with all sections (Implementation Tasks are brief scope descriptions)
• [ ] Validation passed (5 validators)
• [ ] User approved tech-spec
• [ ] status = approved in frontmatter