Spec Update — Post-change Documentation

When to use

• After implementing a feature or fix — update the functional spec for the affected domain
• From /commit step 6 — automatically invoked during the commit workflow
• Standalone — run /spec-update to update docs without committing
• To bootstrap specs on an existing codebase — run /spec-update when no specs exist; init mode activates automatically
• Never for trivial changes (chore, test, perf commits with no user-visible impact)

Process

Step 0: Init mode (bootstrap)

Only when invoked standalone (not from /commit). Skipped if docs/specs/ already contains .md files, unless the user explicitly requests init.

0a. Activation check

• If invoked from /commit step 6 (last git log returns a conventional commit format) → skip to Step 1
• If docs/specs/*.md files already exist AND user did not explicitly request init → skip to Step 1
• Otherwise → enter init mode

0b. Scan codebase for domains

Stack-agnostic, 4-pass heuristic (in order of confidence):

Exclude infrastructure dirs: node_modules, .git, .claude, dist, build, __pycache__, .venv, coverage, docs, config, migrations, assets, public, static, vendor, tests, test.

De-duplicate by normalized name (lowercase, strip - and _). Keep the most descriptive variant.

0c. User validation (Level 3 — mandatory)

Present discovered domains with confidence level and source. The user must confirm, add, remove, or rename domains before any file is written. Never auto-generate without confirmation.

0d. Generate specs

For each confirmed domain, create docs/specs/<domain>.md using the template below:

• Overview: 1-2 sentences inferred from code/README. Prefix with > Draft — to be refined.
• User Stories: 1-2 placeholder stories in Mike Cohn + Gherkin format. Prefix with > Draft — inferred from codebase scan.
• Behavior: one empty scaffold section
• Configuration: empty table (no rows)
• History: | <today> | init | Initial spec generated by /spec-update init |

After generation → go directly to Step 5 (Review). Skip Steps 1-4.

Step 1: Detect scope and type

Skip this step if you just completed Step 0 (init mode). Go directly to Step 5.

Parse the commit message (planned or last) to extract the conventional commit type and scope:

git log -1 --format=%s

Extract: type(scope): description → type = feat, scope = payment, etc.

If scope is absent: infer from the main directory touched in the diff and ask the user to confirm.

Decision matrix:

Step 2: Update Functional Spec (6a)

Target file: docs/specs/<scope>.md

If file does not exist → create from the template below.

If file exists → read it, then:

1. Update Overview if the feature scope expanded
2. Add new User Stories for new capabilities (Mike Cohn + Gherkin format from /user-story)
3. Add or update Behavior sections for changed behaviors
4. Update Configuration if new options were added
5. Append a row to History with date, short commit hash, and change summary

Rules:

• Always incremental update — never recreate from scratch
• Focus on "WHAT" (user perspective), not "HOW" (technical implementation)
• Reuse the Mike Cohn + Gherkin format from the /user-story skill
• If the scope is ambiguous or the domain boundary is unclear → ask the PO

Step 3: Update README (6b)

Check if the change impacts installation, configuration, or usage:

• If the commit is feat and introduces a new user-facing capability:
  • Check if README mentions the affected domain
  • If yes → propose updating the relevant section
  • If no and the change is significant → propose adding a mention
• If the change affects setup/install/config → propose updating the relevant section
• If not relevant → skip silently

Step 4: Lessons Learned (6c)

Evaluate whether the changes reveal:

1. A non-obvious pattern, platform quirk, or debugging lesson
2. A key technical decision worth recording for future reference

If yes → update memory/MEMORY.md (for project-level insights) or memory/patterns.md (for reusable patterns).

If nothing notable → continue without interruption.

Step 5: Review with user

Present a summary of all proposed documentation changes:

• Which files were created or modified
• Key content added or changed
• Ask the user to validate before proceeding

If the user requests changes → iterate. If the user declines → skip without blocking.

Template: Functional Specification

File: docs/specs/<scope>.md

# <Scope> — Functional Specification

> Auto-generated by /spec-update. Last updated: YYYY-MM-DD.

## Overview

[1-2 paragraphs: what this domain does from the user's perspective]

## User Stories

### <Story title>

- **As a** [persona]
- **I want to** [action]
- **so that** [outcome]

**Acceptance criteria:**

- **Given** [context], **when** [action], **then** [result]

## Behavior

### <Behavior name>

- **Trigger:** what initiates this
- **Input:** what the user provides
- **Output:** what the user sees/gets
- **Edge cases:** known edge cases handled

## Configuration

| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |

## History

| Date | Commit | Change |
| ---- | ------ | ------ |
| YYYY-MM-DD | `abc1234` | Initial specification |

Rules

• Advisory — never blocking. The user can always decline documentation updates
• Focus on "WHAT" (user perspective), not "HOW" (technical details)
• Always read existing files before modifying — never overwrite blindly
• Incremental updates only — never recreate a spec from scratch
• If scope is ambiguous → ask the PO for confirmation
• When in doubt at any step → ask the PO via AskUserQuestion before continuing (never guess intent)
• Init mode requires user confirmation of domain list before any file is created (Level 3 gate)
• Init specs are draft scaffolds — real content accumulates through incremental updates after commits

Common Pitfalls

• Over-documenting internals: Specs describe user-visible behavior, not code structure. "The payment module uses Stripe webhooks" is too technical. "Users receive a confirmation email after payment" is correct.
• Stale specs: If a spec exists but is outdated, update it — don't create a new one. One spec per domain, always current.
• Scope creep: Only document what changed in this commit, not the entire domain. The spec grows incrementally over time.
• Missing the audience: Specs are for the PO and future developers to understand WHAT the system does. Architecture docs (see /doc-generate) cover HOW.
• Confusing init with complete documentation: Init generates scaffolding with placeholder text, not authoritative specs. The real content grows via incremental /spec-update after each /commit. Don't treat init output as final.

References

Related Skills

• /commit — Invokes this skill at step 6
• /user-story — Mike Cohn + Gherkin format reused for user stories
• /doc-generate — Architecture, API, and onboarding documentation (complementary)
• /review — May flag missing documentation

Inspiration

• claude-code-spec-workflow — spec-driven development workflow
• cc-sdd — Kiro-style spec-driven development