| name | kata-spec |
| description | Write specifications (WHAT/WHY) for features, changes, and improvements. Spec is approved when `wiki/STATUS.md` shows the spec row at `spec approved` — written there by a human signal (label, comment, APPROVED review, or in-session message) that `kata-dispatch` or the active agent propagates. Use when proposing changes, capturing findings as actionable specs, or evaluating spec quality. Pair with the `kata-plan` skill for the HOW side.
|
Write and Review Specs
A spec defines WHAT to build and WHY. Spec sits in the spec →
design → plan →
implement pipeline: the spec captures WHAT/WHY,
the design captures WHICH/WHERE, the plan captures HOW/WHEN, and implementation
executes the plan.
Spec and plan are independent deliverables. Only produce the one the user
asked for. If they ask for a spec, write the spec and stop.
When to Use
- Capturing a finding (audit, kata walk, product feedback) as actionable work
- Documenting a proposed feature, change, or improvement with rationale
- Reviewing a spec before it advances to planning ("review spec NNN", "is spec
NNN ready?")
- Co-running with
kata-design when one prompt asks for both — see
lockstep co-execution
Checklists
<read_do_checklist goal="Ensure the WHAT/WHY boundary when writing a spec">
</read_do_checklist>
<do_confirm_checklist goal="Verify spec quality before recommending approval">
</do_confirm_checklist>
Directory Structure
specs/{NNN}-{kebab-case-name}/
spec.md WHAT and WHY (this skill)
design-a.md WHICH and WHERE (the `kata-design` skill)
plan-a.md HOW and WHEN (the `kata-plan` skill)
Numbers are claimed in wiki/STATUS.md (see § Process Step 1) before any
content is written. The directory name pairs the claimed NNN with a
kebab-case slug.
Writing a Spec (WHAT and WHY)
The spec answers two questions: what are we changing, and why does it matter?
Identify which persona and job from JTBD.md the spec serves.
- Problem first. Evidence before proposal — errors, metrics, examples.
- Specific scope. Name affected files, APIs, entities; state what is
excluded.
- Compatibility stance. One line: clean break, or a compat requirement
with its why. Clean break is the default unless CONTRIBUTING.md states a
different policy; silence means clean break downstream. When breaking,
list old-path removal as a success criterion.
- Verifiable success. Each criterion is a claim plus the command or path
that verifies it. One sentence each. No rationale, no alternatives considered.
- No HOW. Name what each component does, not which mechanism implements it.
Tool selection and sequencing belong in the design and plan. Cite evidence
by entity or behaviour name, not by
file:line pointer.
- State the classification. The spec carries a one-line
product-vs-internal classification per the shared rubric in
work-definition.md § Product-aligned vs internal.
Form follows content. Prefer tables for lists with shared structure (files,
criteria, alternatives). Prefer bullets for flat facts. Use prose only for the
narrative thread between them. If a paragraph could be a row, make it a row. Do
not restate what the artifact already shows.
Approval
A spec is approved when wiki/STATUS.md shows its row at spec approved. The
decision is human-only: agents never autonomously originate spec approved.
STATUS is written when a trusted human's signal is observed — <phase>:approved
label, APPROVED review, approval comment on the PR, or a direct message in an
interactive session. kata-dispatch validates trust and propagates PR-side
signals into STATUS; an in-session agent writes STATUS when the user explicitly
approves. See
approval-signals.md
and
coordination-protocol.md § Approval signal.
Phase progression is derived from main: once the spec PR merges,
specs/NNN/spec.md exists on main and the next phase may begin. A STATUS
row at spec approved authorizes the merge but does not by itself advance
the phase.
Reviewing a Spec
Evaluate spec.md against the qualities listed in "Writing a Spec" above,
then run the DO-CONFIRM checklist at the top of this skill. Report your
findings via PR comment so a trusted human reviewing the PR can act on
them.
Do not recommend approval, and do not apply the spec:approved label.
Deciding on approval is a human-only action. The release engineer detects
approval signals across multiple channels — labels, PR comments, APPROVED
reviews, in-session user messages — and reads wiki/STATUS.md as the
canonical record. Your job here is to evaluate quality and surface
findings, not to gate the approval signal.
If criteria fall short, request changes via PR comment.
Process
Step 0: Read Memory
Read wiki/MEMORY.md, then run fit-wiki boot --agent <self> per
memory-protocol § On-Boot Read Set.
The digest's owned_priorities, claims, and storyboard_items seed this
Process.
Extract specs previously written and any deferred work from prior entries.
Step 1: Claim the spec number
Read wiki/STATUS.md and pick the next available id — the next multiple of 10
above the current highest. Append a {NNN}\tspec\tdraft row to STATUS.md and
commit the wiki. The Stop hook pushes wiki commits, so the claim becomes
visible to other sessions immediately and parallel PRs cannot collide on the
same number. If the spec is later abandoned, transition the row to
{NNN}\tspec\tcancelled rather than deleting it.
Step 2: Clarify
Ask about motivation, scope, constraints, and success before writing.
Step 3: Research
Read relevant code, data, and existing specs.
Step 4: Write the spec
WHAT and WHY only. Write specs/NNN/spec.md locally using the id claimed in
Step 1; do not push yet.
Step 5: Clean sub-agent review panel
Follow the kata-review caller
protocol, invoked on the local
specs/NNN/spec.md before push. Tell each reviewer not to invoke
kata-spec. Address every confirmed blocker/high/medium finding before
opening the PR — the PR should not become visible to kata-dispatch until the
panel is clean.
Step 6: Open a spec PR
The PR title carries the spec id: spec(NNN): …. Merge of that PR is what
advances the phase. Apply the matching product / internal label per the
shared rubric when opening the PR. Do not apply the spec:approved label and
do not recommend approval — those are human-only actions; see § Approval.
Under
lockstep co-execution, do
not open a separate spec PR — the spec ships inside the single combined PR
opened at the design stage.
Hold every published body to
citation integrity.
Memory: What to Record
Append to the current week's log (see agent profile for the file path):
- Specs written — Spec number, name, and status
- Review results — Specs reviewed and disposition (approved/changes needed)
- Deferred work — Findings not yet captured as specs
- Metrics — Append one row per run to
wiki/metrics/{skill}/
per references/metrics.md. See KATA.md § Metrics for the
recording-eligibility rule.
