# Zot Mini Spec Mini Spec > Mini-spec - Skill: `tomevault-io/zot-mini-spec-mini-spec` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/zot-mini-spec-mini-spec` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/zot-mini-spec-mini-spec/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/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:** ```bash # 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: ```markdown # 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: ```markdown # ClassName **Requirements:** R1, R3, R7 ``` Use minispec to add requirement references: ```bash ~/.claude/bin/minispec update add-ref crc-Store.md R5 ``` **Artifacts Format** (must be exact for `minispec` tool parsing): ```markdown ## 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: ```bash ~/.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: ```markdown - [ ] 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 ```markdown # 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 ```markdown # 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 ` 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 ```bash # 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](https://tomevault.io/claim/zot) — claim your Tome and manage your conversions.