Tech Spec Planning

Tech Spec Planning

This skill creates the technical plan that sits between idea and coding.

Use it when:

• the feature is approved but implementation is not planned yet
• you need architecture decisions before coding
• a task is too big to start coding blindly
• you want a clean breakdown of files, risks, and tests

Main benefit:

• lowers random coding
• exposes missing decisions early
• gives execution a clear technical path

Output

Default output:

• work/<feature>/tech-spec.md

For the recommended structure, read template.md.

Inputs

Read:

• work/<feature>/user-spec.md
• relevant files from docs/project_knowledge/
• the code that will actually be affected

Workflow

1. Confirm the feature scope from user-spec.md.
2. Research the relevant code paths, configs, and integrations.
3. Identify technical decisions and constraints.
4. Produce a technical spec that covers:
   • solution shape
   • architecture changes
   • dependencies
   • testing strategy
   • risks
   • implementation tasks by waves
5. Keep all implementation tasks brief and outcome-focused.

Rules

• Every major decision should trace back to a user requirement or be marked as purely technical.
• Flag any deviation from user intent explicitly.
• Keep task descriptions short; detailed execution belongs later.
• Prefer real file paths and real integration points over invented abstractions.
• If the plan becomes too large, propose MVP and extension phases.

Validation Mindset

Before presenting the tech spec, self-check:

• does it match the user spec
• does it match the actual codebase
• does the testing depth fit the feature size
• are there obvious missing dependencies or fake references