Zot Mini Spec Mini Spec

Mini-spec

Design Docs First — Not Code

When understanding a feature or planning a change, start with design/design.md and the relevant CRC cards/sequences BEFORE using code exploration tools. Design docs are the project index — they show component relationships, responsibilities, and code file mappings more efficiently than code search. Only drop into code-level tools (Serena, Grep, etc.) after the design docs have oriented you.

Prerequisite: Version Check and Comment Patterns

First, run ~/.claude/bin/minispec check-version to verify the tool is installed and matches this skill's version. If it fails, warn the user: the tool and skill must be the same version or there will be compatibility issues.

Then, run ~/.claude/bin/minispec query comment-patterns to learn the recognized comment patterns for traceability comments in code files.

MANDATORY: Create Tasks First

BEFORE reading any files or doing any work, create tasks for applicable phases:

TaskCreate: "Spec Phase: [feature name]"
TaskCreate: "Requirements Phase: [feature name]"
TaskCreate: "Design Phase: [feature name]"
TaskCreate: "Implementation Phase: [feature name]"
TaskCreate: "Simplification Phase: [feature name]"
TaskCreate: "Gaps Phase: [feature name]"

Do NOT proceed until tasks exist. This is required for user visibility into progress.

Overview

3-level architecture: specs → design → code.

specs/    # Human intent — what to build and why, in the user's own words
design/   # AI translation — requirements.md, crc-*, seq-*, ui-*, test-*, manifest-ui.md
docs/     # user-manual.md, developer-guide.md
src/      # Code with traceability comments

What each level is for

Specs are the human's voice. They describe what the system should do in natural language, organized by feature area. The user writes or approves them. They communicate intent — not implementation, not internal structure. A spec should read like someone explaining the feature to a colleague. For libraries, API signatures belong in specs because they are the face of the project — they must be agreed upon before design begins. Specs must state the language and environment so the AI knows what it's building for.

Design is the AI's translation of specs into buildable structure. Requirements extract testable statements. CRC cards assign responsibilities to components. Sequences show how components interact. The user reviews this translation before code is written — catching a misunderstanding here costs minutes, not hours.

Code implements the design with traceability comments linking back to the design artifacts that justify each component's existence.

Why this matters

Each level exists because skipping it has a concrete cost:

• Verification — Design is smaller than code. The user can confirm you understood the task before you write hundreds of lines.
• Preview — The design tells the user what you're about to change. Without it, they discover unwanted modifications after the fact.
• Reference — During implementation, you look up the design instead of re-reading all the code. This keeps changes consistent across files.
• Anchor — Without a design document, iterative modifications cause drift: features silently disappear as code evolves across sessions. The design pins what must survive.
• Traceability — The specs→requirements→design chain ensures nothing is lost between what the user asked for and what gets built. When something breaks, you can trace backward to find out why.

The phases are not ceremony. They are cheaper than debugging a misunderstood requirement after 500 lines of code.

Task Tracking

During implementation, break down into per-file tasks:

TaskCreate: "Implement view.ts changes"
TaskCreate: "Implement viewlist.ts changes"
TaskCreate: "Update design docs"

Mark phases complete with TaskUpdate as you finish them. Use Quality Checklist items as tasks before finalizing.

Core Principles

• use SOLID principles, comprehensive unit tests
• when adding code, verify whether it needs to be factored
• Code and specs as MINIMAL as possible
• Before using a callback, see if a collaborator reference would be simpler
• write idiomatic code for the language you use
• avoid holding locks in sections that have significant functionality
• No unanchored design: every design artifact must trace back to a spec item and requirement. If you need to add something to the design, add it to specs first, then requirements, then design. This applies regardless of direction — even when documenting existing code, verify the spec anchor exists before updating design. This prevents features from existing only in the AI's interpretation.

Why anchoring matters

Specs and design docs are the project's memory bank. AI context dies every session — code changes compound across sessions without any single agent seeing the full history. Unanchored code has no justification trail: a future session can't tell whether a function was designed or accidental, required or leftover. When that session makes changes, unanchored features silently disappear because nothing in the design said they should exist.

Anchoring is cheap (a few lines of spec + a requirement number). The cost of not anchoring is discovering, three sessions later, that a feature vanished during an unrelated refactor and no one noticed because the design never mentioned it. The spec is the pin that says "this must survive."

Cross-cutting Concerns

design.md Cross-cutting Concerns section: Patterns spanning components (auth, errors, logging, routing, theming). Referenced from other design artifacts: Cards, sequences, and layouts can all say "see cross-cutting: auth"

Traceability

design.md Artifacts section: design files with code file checkboxes.

Use minispec commands for checkbox operations:

# View current artifact states
~/.claude/bin/minispec query artifacts

# Before modifying code: uncheck the artifact
~/.claude/bin/minispec update uncheck design.md crc-Store.md

# After implementation matches design: check the artifact
~/.claude/bin/minispec update check design.md crc-Store.md

Code changes: Uncheck artifact, ask user: "Update design, specs, or defer?" Update design: Read code, update design file, re-check artifact.

Workflow

First: Read specs. Specs must indicate language/environment.

Then: Proceed through phases

1. Spec Phase Create in specs/: human-readable descriptions organized by feature area. Specs are the user's intent in their own words. For applications, this means behavior and user-facing concepts. For libraries, include the public API signatures — they are the contract that design must satisfy. Do not include internal structure or implementation choices.

Upon completion, run ~/.claude/bin/minispec phase spec to verify spec files exist, then offer Requirements Phase. Do not jump to Design.

2. Requirements Phase Create design/requirements.md: merge all specs into numbered requirements.

Format:

# Requirements

## Feature: [feature-name]
**Source:** specs/feature.md

- **R1:** [requirement from spec]
- **R2:** [requirement from spec]
- **R3:** [inferred requirement - marked as such]

## Feature: [another-feature]
**Source:** specs/another.md

- **R4:** [requirement]

Guidelines:

• Each spec item becomes exactly one numbered requirement (R1, R2, ...)
• Numbering is global across all features (not per-feature)
• Mark inferred requirements explicitly: "R5: (inferred) ..."
• Keep requirement text atomic and testable

Upon completion, run ~/.claude/bin/minispec phase requirements to verify format, then offer Design Phase. Do not jump to Implementation.

3. Design Phase Create in design/:

• design.md: Intent + Artifacts (design files → code file checkboxes)
• crc-*: CRC cards (see format below)
• seq-*: sequence diagrams (≤150 chars wide)
• ui-*: ASCII layouts, reference CRC cards
• test-*: test designs (see format below)
• manifest-ui.md: routes, theme, global components

Design Traceability: All design artifacts must reference requirements:

# ClassName
**Requirements:** R1, R3, R7

Use minispec to add requirement references:

~/.claude/bin/minispec update add-ref crc-Store.md R5

Artifacts Format (must be exact for minispec tool parsing):

## Artifacts

### CRC Cards
- [x] crc-Store.md → `src/store.ts`
- [x] crc-View.md → `src/view.ts`, `src/viewlist.ts`

### Sequences
- [x] seq-crud.md → `src/store.ts`, `src/view.ts`

### UI Layouts
- [ ] ui-dashboard.md → `web/html/dashboard.html`

### Test Designs
- [ ] test-Store.md → `src/store_test.ts`

The Artifacts section is a manifest of all design files except design.md and requirements.md. Every crc-, seq-, ui-, test-, and manifest-*.md must be listed.

Format rules:

• Section headers (### CRC Cards, etc.) are optional grouping
• Each line: - [x] design.md → code-file(s) or - [ ] design.md
• Multiple code files: comma-separated after →
• Backticks around code paths are optional
• Checkbox state applies to all code files on that line

Upon completion, run ~/.claude/bin/minispec phase design to verify coverage, then offer Implementation Phase. Do not jump to Gaps.

4. Implementation Phase Add traceability comments:

// CRC: crc-Store.md | Seq: seq-crud.md
add(data): Item {

Block-comment languages: The minispec query comment-patterns output lists any comment_closers. If a closer exists for the file extension, you MUST append it to every traceability comment. An unclosed block comment silently swallows all subsequent code. See config-reference.md (in this skill directory) if you need to configure closers for a new language.

Mark implemented using minispec:

~/.claude/bin/minispec update check design.md crc-Store.md

Look out for language-specific "gotchas" like mixing functions and methods in Lua.

Upon completion, run ~/.claude/bin/minispec phase implementation to verify traceability, then run the Simplification Phase.

5. Simplification Phase Invoke the code-simplifier agent on the recently modified code. This refines code for clarity, consistency, and maintainability while preserving functionality.

Upon completion, proceed to Gaps Phase.

6. Gaps Phase

Traceability Verification:

Run ~/.claude/bin/minispec phase gaps to validate the gaps section, then run ~/.claude/bin/minispec validate for full coverage check:

1. Specs ↔ Requirements: Each spec item maps to exactly one requirement in requirements.md
2. Requirements ↔ Design: Each requirement is referenced by at least one design artifact

design.md Gaps section tracks (use S1/R1/D1/C1/O1/A1 numbering):

• Spec→Requirements (Sn): Spec items not captured in requirements.md
• Requirements→Design (Rn): Requirements without design artifacts referencing them
• Design→Code (Dn): Designed features without code
• Code→Design (Cn): Code without design artifacts
• Oversights (On): Missing tests, tech debt, enhancements, security concerns, etc.
• Approved (An): Approved gap, never checked off to ensure they stay in place

Nest related items with checkboxes:

- [ ] R1: Requirement R5 has no design artifact
- [ ] O1: Test coverage gaps
  - [ ] Feature A (5 scenarios)
  - [ ] Feature B (3 scenarios)
- [ ] A1: Dangling methods, these are never called
  - [ ] Maluba.go: Maluba.Frobnicate, Maluba.Enreify

Upon completion, offer to update Documentation (Documentation Phase).

7. Documentation Phase, Optional -- offer to user after Gaps Create docs/user-manual.md and docs/developer-guide.md with traceability links.

CRC Card Format

# ClassName
**Requirements:** R1, R3, R7

short description

## Knows
- attribute: description
## Does
- behavior: description
## Collaborators
- OtherClass: why
## Sequences
- seq-scenario.md

Principles: Single Responsibility, minimal collaborations, PascalCase.

Test Case Format

# Test Design: ComponentName
**Source:** crc-ComponentName.md
## Test: name
**Purpose:** what this validates
**Input:** setup and data
**Expected:** verifiable outcome
**Refs:** crc-*.md, seq-*.md

Cover: happy path, errors, edge cases.

Quality Checklist

• Requirements: all spec items captured, numbered (R1, R2, ...), inferred items marked
• CRC Cards: nouns/verbs covered, no god classes, Requirements linked
• Sequences: participants from CRCs, ≤150 chars wide
• UI Specs: ASCII layouts, refs to CRCs and manifest-ui.md
• Traceability: design files in Artifacts, code files have checkboxes, all Rn referenced
• Tests: test-*.md for key behaviors
• Phase validation: ~/.claude/bin/minispec phase <phase> passes after each phase
• Full validation: ~/.claude/bin/minispec validate passes

Minispec Tool

The minispec CLI tool (at ~/.claude/bin/minispec) performs structural operations on design files.

IMPORTANT: Always use minispec commands instead of manual editing for:

• Checking/unchecking artifact checkboxes
• Adding requirement references to CRC cards
• Querying artifact states and coverage

# Version check (run on skill load)
~/.claude/bin/minispec check-version         # Verify tool and skill versions match

# Phase-specific validation (run after each phase)
~/.claude/bin/minispec phase spec            # Verify spec files exist
~/.claude/bin/minispec phase requirements    # Verify requirements format
~/.claude/bin/minispec phase design          # Verify design files and coverage
~/.claude/bin/minispec phase implementation  # Verify code traceability
~/.claude/bin/minispec phase gaps            # Verify gaps section

# Full validation
~/.claude/bin/minispec validate              # Run all validations

# Queries
~/.claude/bin/minispec query artifacts       # Show all artifacts with checkbox states
~/.claude/bin/minispec query uncovered       # List Rn without design refs
~/.claude/bin/minispec query gaps            # List gap items
~/.claude/bin/minispec query requirements    # List all requirements

# Updates - artifact checkboxes (in design.md)
~/.claude/bin/minispec update check design.md crc-Store.md     # Check artifact
~/.claude/bin/minispec update uncheck design.md crc-Store.md   # Uncheck artifact

# Updates - requirement references (in CRC cards)
~/.claude/bin/minispec update add-ref crc-Store.md R5          # Add requirement to CRC
~/.claude/bin/minispec update remove-ref crc-Store.md R5       # Remove requirement from CRC

# Updates - gaps
~/.claude/bin/minispec update add-gap O "Test coverage needed" # Add oversight gap
~/.claude/bin/minispec update resolve-gap O3                   # Mark gap resolved
~/.claude/bin/minispec update approve-gap D3                   # Convert gap to approved (A) type

Use the tool to:

• Run phase-specific checks after completing each workflow phase
• Verify design file formats are parseable
• Find uncovered requirements quickly
• Toggle checkboxes atomically (avoid manual checkbox edits)
• Add/remove requirement references to CRC cards
• Add gaps with auto-numbering

Converted and distributed by TomeVault — claim your Tome and manage your conversions.