tech-spec
/tech-spec
Tech spec generation and review. Use when: designing features, writing specs, spec review. Not for: requirements analysis (use req-analyze), implementation (use feature-dev), architecture advice (use codex-architect). Output: numbered tech spec document.
- Author
- sd0xdev ↗
- Repository
- sd0x-harness ↗
- Licence
- MIT
- Last repository change
- 08.10.2026
Assessment and security
- Files in this package
- 3
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 08.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Tech spec generation and review. Use when: designing features, writing specs, spec review. Not for: requirements analysis (use req-analyze), implementation (use feature-dev), architecture advice (use codex-architect). Output: numbered tech spec document.
Original author description
Tech spec generation and review. Use when: designing features, writing specs, spec review. Not for: requirements analysis (use req-analyze), implementation (use feature-dev), architecture advice (use codex-architect). Output: numbered tech spec document.
How it works
- Trigger
- When NOT to Use
- Commands
- Context-Aware Mode (Upsert)
- Workflow
- Spec Structure
- Write-Time Budget
- Output
- Verification
- References
SKILL.md preview
---
name: tech-spec
description: "Tech spec generation and review. Use when: designing features, writing specs, spec review. Not for: requirements analysis (use req-analyze), implementation (use feature-dev), architecture advice (use codex-architect). Output: numbered tech spec document."
allowed-tools: Read, Grep, Glob, Bash(git:*), Write
---
# Tech Spec Skill
## Trigger
- Keywords: tech spec, technical specification, spec review, review spec, feature design
## When NOT to Use
- Creating request documents (use /create-request)
- Code implementation (use feature-dev)
- Architecture consulting (use /codex-architect)
## Commands
| Command | Purpose | When |
| --------------- | -------------------- | ----------------------- |
| `/tech-spec` | Create or update tech spec | Auto-detects create/update from filesystem state |
| `/deep-analyze` | Deepen spec + roadmap | After initial concept |
| `/review-spec` | Review tech spec | Spec confirmation |
## Context-Aware Mode (Upsert)
When invoked without a full requirement description, the skill auto-detects the target feature using
the cascade in `references/native-feature-resolution.md` — this skill's own reference, and
deliberately command-free.
This skill grants `Bash(git:*)` and not `Bash(node:*)`, so the resolver script is not a command it
may run — and it does not link the shared reference that teaches it, because a file of unrunnable
commands inside this skill's reachable graph is the defect, not the annotation on it. The cascade
needs nothing beyond `$ARGUMENTS`, `git branch --show-current`, `git diff --name-only HEAD` and a
`Glob` over `docs/features/*`. What that does **not** produce is the four document source sets or
`scan_error` — this skill consumes neither. A skill that needs the sets (`/architecture`,
`/tech-brief`, `/runbook`, `/ask`) grants `Bash(node:*)` and reads the shared reference itself.
**Canonical discovery is still owed, and testing one literal path does not deliver it.** The spec
may have been split into a folder or may carry a variant name, and `docs/features/auto-loop-evolution/2-tech-spec/2-tech-spec.md`
in this repo is the live proof. Resolve it with a `Glob` over `docs/features/<key>/`, in this
order — the first hit wins:
| # | Glob | Meaning |
|---|------|---------|
| 1 | `docs/features/<key>/2-tech-spec.md` | Unsplit canonical spec |
| 2 | `docs/features/<key>/2-tech-spec/2-tech-spec.md` | Split spec — the folder keeps the lifecycle prefix, the main file keeps the canonical filename (`@rules/docs-numbering.md` § Size Limit) |
| 3 | `docs/features/<key>/2-tech-spec*.md`, **minus** any hit matching `-fp-brief.md` or `-tech-brief.md` | A variant (`2-tech-spec-v2.md`). The two suffixes are excluded because they are not specs: `scripts/config/doc-taxonomy.json` carries the same `exclude_pattern` for the same reason, and `docs/features/seek-verdict/` holds a live `2-tech-spec-fp-brief.md` that this glob would otherwise return as the canonical spec. **Two or more remaining hits is ambiguity, not a match** — report and take the Need Human exit rather than picking one |
Requirements docs (`1-requirements.md`) resolve the same three ways, **without** the suffix
exclusion — `doc-taxonomy.json` carries `exclude_pattern` on the `tech-spec` type only, and copying
it to requirements here would put this skill out of step with the classifier rather than in step. A `Glob` that errors, or a
`<key>` that resolved with `low` confidence and matches nothing, is **not** the same as "no spec
exists" — say which of the two it was; do not silently drop into create mode.
A fourth lookup resolves the **intent artifact**: exactly `intent-<key>.md` in the feature
directory — the exact name, never a wildcard pick. A separate `Glob intent-*.md` only surfaces
strays or wrong-key files (report them; never adopt one as the intent).
| Filesystem State | Action |
|-----------------|--------|
| Canonical discovery finds exactly one spec | **Update mode**: read that file — at the path discovery returned, not at the literal `2-tech-spec.md` — research code changes since last update, incrementally update changed sections |
| All three globs empty | **Create mode**: generate new spec from template at `docs/features/<key>/2-tech-spec.md` |
| Glob 3 returns two or more | Gate: Need Human — ambiguous canonical spec, name the candidates |
| Feature not resolved | Gate: Need Human |
In **create mode**, if `intent-<key>.md` is absent, write it first from the intent template
bundled with `/req-analyze` — distilled from the requirement clarification step (constraints
only, ≤60 lines) — then write the spec. If present, read it before designing.
In **update mode**, focus on sections affected by recent code changes (use `git diff` to identify). Preserve unchanged sections. If `intent-<key>.md` is absent, create it exactly as in
create mode (projecting from `1-requirements.md` §§ 1–2 when present, else from the spec's
requirement summary) — this is what lets the `next-step` advisory converge on features whose
spec predates the intent mechanism. When it exists, read it: every spec section that contradicts
an `INV-*` or Non-goal is a **conflict to surface to the user, not to paper over** — and never
rewrite intent to match a spec; amending intent is a human re-decision.
## Workflow
```mermaid
sequenceDiagram
participant A as Analyst
participant C as Codebase
participant D as Document
A->>A: 1. Requirement clarification
A->>C: 2. Code research
C-->>A: Related modules
A->>A: 3. Solution design
A->>A: 4. Risk assessment
A->>A: 5. Work breakdown
A->>D: 6. Output document
```
## Spec Structure
1. Requirement summary (problem + goals + scope)
2. Existing code analysis
3. Technical solution (architecture + data model + API + core logic)
4. Risks and dependencies
5. Work breakdown
6. Testing strategy
7. Open questions
## Write-Time Budget
A spec is cheapest to keep short while it is being written. Enforcing length afterwards means either
a split or a prune, and both cost a review round that writing to budget would have avoided.
| Lines (`wc -l`) | At write time |
|-----------------|---------------|
| ≤ 300 | The target. Aim here |
| 301–400 | Acceptable — trim before adding more |
| > 400 | **State the cohesion exception in the document itself**, or prune / split before it is written. "I ran out of room" is not the exception |
The exception is a sentence in the spec naming why these sections are one argument that does not
read better apart. Unstated, a spec over 400 lines is over budget, and `@rules/docs-numbering.md`
§ Size Limit takes it from there — prune first, then merge, then split.
What to leave out: alternatives considered and rejected (one line each, not a section), history of how
the design changed (that belongs in a record), and anything the code will state more precisely than
prose can.
In **update mode**, a section the code made obsolete is pruned, not annotated. Rewriting it in place
keeps the spec current-authority; layering "previously..." notes turns it into a record it is not.
## Output
Numbered tech spec document with sections: Overview, Requirements, Architecture, Implementation plan, Work breakdown, Testing strategy, Open questions.
## Verification
- Solution covers all requirement points
- Architecture diagrams use Mermaid
- Risks have mitigation strategies
- Work can be broken into trackable items
- Within the write-time budget, or the cohesion exception is stated in the document
## References
- `references/template.md` - Spec template + review dimensions
## File Location
```
docs/features/{feature}/
├── 2-tech-spec.md # Technical spec (numbered per docs-numbering rule)
├── requests/ # Request documents
└── README.md # Feature description
```
## Examples
```
Input: /tech-spec "Implement user asset snapshot feature"
Action: Requirement clarification -> Code research -> Solution design -> Output document
```
```
Input: /review-spec docs/features/xxx/2-tech-spec.md
Action: Read -> Research -> Review -> Output report + Gate
```
Files in this package (3)
- SKILL.md 8 KB
- references/native-feature-resolution.md 5 KB
- references/template.md 2 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · sd0xdev/sd0x-harness | 100 | MIT |
| duc01226/EasyPlatform | 100 | MIT |
| duc01226/EasyPlatform | 100 | MIT |
| max4c/skills | 100 | MIT |
| dimagi/dimagi-claude-workflows | 90 | MIT |
Database snapshot: 13.11.2026 · package version 9971e756d4ed (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100dev-spec
Write the architecture and per-area tech specs from the PRD (or, on Standard, the slice's own Behaviours), and copy the default principles into the project. Use for "write the tech spec", "design the architecture", "how should we build it", or when dev reaches the spec step. - 100architecture
Architecture design and documentation. Produces 3-architecture.md with component diagrams, data flow, integration points, and architecture decisions. Reads existing tech-spec as input. Use when: designing system architecture, documenting component interactions, creating… - 95gvm-tech-spec
Use when creating technical specifications from a requirements document. Triggered by /gvm-tech-spec command, requests to create a tech spec, or requests to design system architecture. Reads requirements and test cases, produces multiple focused spec documents with adaptive… - 100spec-driven-implementation
Drive a spec-first workflow for substantial features by writing PRODUCT.md before implementation, writing TECH.md when warranted, and keeping both specs updated as implementation evolves. Use when starting a significant feature, planning agent-driven implementation, or when the… - 100write-tech-spec
Write a TECH.md spec for a significant Warp feature after researching the current codebase and implementation constraints. Use when the user asks for a technical spec, implementation plan, or architecture doc tied to a product spec. - 90create-tech-spec
Create a technical spec from a GitHub issue in this repository by applying the shared `write-tech-spec` workflow with Oz-specific issue context and output paths. Use when an issue should be turned into a tech spec artifact stored under `specs/GH<issue-number>/tech.md` and the…