skills/feature-spec/SKILL.md

name, description

name	description
feature-spec	Write a tight implementation-level spec for a single feature or component before coding it. Use after a project-level spec exists (see spec-driven-dev) and you need to nail down one feature inside it.

Feature Spec

Overview

A feature spec is the implementation-level contract for one feature or component, written by an engineer before code. It is shorter and more focused than a project-level spec (spec-driven-dev) — it assumes the project context, the stack, and the user are already known. Its job is to force one decision: what does done look like, and what is explicitly not in this feature.

Core principle: If you cannot write three measurable success criteria, you do not understand the feature well enough to build it.

When to Use

• About to start implementing a feature inside an existing, already-specced project
• A change that touches more than one file or one package
• A change that introduces a new public API, schema, or external contract
• Any time the requirements feel "obvious" — that feeling usually means assumptions are stacking silently

When NOT to use:

• Project kickoff or first-time architecture decisions — use spec-driven-dev instead, which covers the broader lifecycle (Objective, Tech Stack, Project Structure, Boundaries, etc.)
• Single-line fixes, typos, dependency bumps
• Spike or throwaway prototypes (note them as such; no spec needed)

Iron Laws

1. Success criteria must be measurable. "The system is fast" is banned. "p99 < 200ms under 100 RPS" is valid. If you cannot state a measurement, the criterion is not a criterion.
2. An "Out of scope" section is mandatory. If you do not draw the boundary, the implementer (you, future-you, or another agent) will guess wrong.
3. Every technical decision in "Technical approach" must have a rationale. A decision is any choice where a reasonable alternative existed and was not taken. "Use Postgres" is not a decision; "use Postgres because the rest of the stack uses it and we need transactions across user + invoice" is.

Spec Template

# Spec: [Feature Name]

## Problem Statement

What problem does this feature solve? For whom? Why now?
(2-4 sentences. If you cannot answer "why now," ask before writing the rest.)

## Success Criteria

- [ ] Criterion 1 — measurable and verifiable
- [ ] Criterion 2 — measurable and verifiable
- [ ] Criterion 3 — measurable and verifiable

## Constraints

Non-negotiable requirements the solution must satisfy.
Examples: "must not change the public API", "must complete in < 500ms",
"must not require a database migration", "must work offline".

## Out of Scope

What this feature explicitly does NOT do, even if related.
Anything plausibly in scope that you decided to defer goes here.

## Technical Approach

The architecture or design decisions, with rationale for each.
Each bullet should answer "why this choice over the obvious alternative."

## Risks

What could go wrong, and how it would be mitigated or detected.
At least one risk must be listed; "no risks" usually means insufficient analysis.

Worked Example

# Spec: IBAN extraction from Swedish PDF invoices

## Problem Statement

Invoice processors at small accounting firms manually copy IBANs from PDF
invoices into the banking system. The current parser handles ~60% of formats;
40% require manual fallback, defeating the automation premise.

Why now: the pilot customer is onboarding three new firms next month, all of
which use formats currently in the 40%.

## Success Criteria

- [ ] IBAN extracted correctly from ≥ 95% of a 200-invoice test corpus
- [ ] Zero false positives (extracting a non-IBAN string as an IBAN) on the corpus
- [ ] p99 extraction time < 500ms per invoice
- [ ] Returns a structured error (not a panic) for unrecognized formats

## Constraints

- Must not require a new dependency (PDF library is already chosen)
- Must work without network access (no external IBAN validation API)
- Must be callable from the existing `Parser.Extract(ctx, r)` signature

## Out of Scope

- Non-Swedish IBAN formats (separate spec when needed)
- BIC/SWIFT extraction (handled by a separate parser)
- OCR — input is assumed to be text-extractable PDF, not scanned image
- Validating that the IBAN refers to a real account

## Technical Approach

- Layered regex-then-checksum approach: regex narrows candidates, MOD-97
  checksum validates. Rationale: pure regex is too permissive; pure
  checksum requires too many candidates to test.
- Use the existing `pdfplumber` text layer rather than re-extracting.
  Rationale: extraction is already the slow path; reusing the layer
  avoids doubling extraction time.
- Return `(iban string, ok bool, err error)` not `(*IBAN, error)`.
  Rationale: the caller almost always wants to know "did we find one"
  separately from "did extraction itself fail," and a pointer return
  invites nil-deref bugs.

## Risks

- Regex tuned to current corpus may overfit; mitigation: corpus is held out
  per-firm, so we will see degradation at the next firm onboarding before
  it reaches production.
- MOD-97 implementation bugs are subtle; mitigation: cross-check against
  the Wikipedia reference implementation in tests.

Common Rationalizations

Rationalization	Reality
"It's a small feature, I don't need a spec"	Small features still need a measurable definition of done. The spec stays small too.
"I'll write the spec after, when I know more"	Then it is documentation, not a spec. The point is forcing clarity before the code locks in your assumptions.
"The success criteria are obvious"	If they are obvious, they are easy to write down. If they are hard to write down, they are not obvious.
"I don't have time to enumerate out-of-scope items"	You will spend more time arguing over scope creep at review than writing this section now.

Brain MCP Integration

The brain holds prior feature specs across the project. Use it to keep constraints and out-of-scope decisions coherent across related features.

At spec start:

• Run brain_query for prior specs in the same area or for the same problem domain. Reusing the same constraints and out-of-scope decisions across related features keeps the system coherent.

After spec is approved:

• Run brain_write with the spec's success criteria and out-of-scope list. Future related specs can cross-reference rather than re-derive.

Logging

Call session_log once at the end of every phase to record the outcome. Pass-rate is computed downstream by the /pass-rate HTTP endpoint, which treats pass as success, fail as failure, skip as neither.

At end of each phase:

• session_log with {skill: "feature-spec", phase: "<phase-name>", final_status: "pass" | "fail" | "skip", message: "<one-line summary>", duration_ms: <wall-clock>, project_root: "<absolute path>"}

Phases for this skill: draft

Status semantics:

• pass — the phase's intended outcome was reached (spec drafted and approved).
• fail — the phase's intended outcome was NOT reached (spec rejected, blocked on unresolved questions).
• skip — phase was skipped intentionally.

Why this matters: the routing pod (Plan 6) reads pass-rate to decide whether to route a future call to a local model. If your skill never logs, the routing pod sees no data.

Mode 2 Routing Note

Spec writing requires interpretation of intent and tradeoff reasoning — work where Claude generally outperforms a 9-13B local model. This skill is intentionally not a Mode 2 routing candidate. In Mode 2, the routing layer should leave feature-spec calls on Claude.

Cross-References

• Load spec-driven-dev instead if this is the first spec for a project (broader template, includes tech stack, project structure, boundaries).
• Load problem-analysis skill before this if the problem statement itself feels fuzzy.
• Load tdd skill once the spec is approved — each success criterion becomes a test.
• Load planning skill if the spec implies more than ~5 implementation tasks.