| name | arnold-rules |
| description | Arnold documentation-first development rules. Reference these rules when: (1) the user runs any /arnold: command, (2) docs/overview.md exists with Arnold's format (What We're Building / Core Features headers), (3) the user explicitly mentions Arnold, documentation drift, or spec alignment. Do NOT activate for projects that have a docs/ folder but no Arnold-generated content. |
| user-invocable | false |
Arnold — Documentation-First Development
This project uses Arnold for doc-centered development.
The docs/ folder is the source of truth for what this
project should be and how it should behave.
Before Writing Code
- Check
docs/ for the relevant feature folder
- Read the feature overview — understand the rules and flows
- If docs don't exist for what you're about to build, create them first
- Check
docs/unknowns.md — is there an unresolved question that affects this?
- Check
docs/decisions/ — has a relevant decision already been made?
After Writing Code
- If you built something new that isn't documented, note it
- If you changed behavior described in docs, flag it
- If you made a significant decision (chose a library, picked an approach),
create a record in
docs/decisions/
- If you discovered something unexpected, add it to the feature's
edge cases or to
docs/unknowns.md
Document Structure
Docs are organized by feature, not by document type:
docs/
├── overview.md # Project vision and goals
├── spec.md # Technical specification (stack, architecture, constraints)
├── status.md # What's done, in progress, blocked
├── milestones.md # Phase tracking (if using milestones)
├── [feature-name]/ # One folder per feature
│ ├── [feature-name]-overview.md # What it does, core rules, acceptance criteria
│ ├── [feature-name]-[flow].md # Step-by-step user flows
│ └── [feature-name]-edge-cases.md # Error handling and unusual scenarios
├── issues/ # Bug reports (auto-numbered)
│ └── NNN-title.md # Severity, repro steps, affected feature
├── decisions/ # Why we chose what we chose
│ └── NNN-title.md # Auto-numbered decision records
├── requests.md # Feature requests and enhancements
├── unknowns.md # Open questions and bets
├── archive/ # Stale docs kept for historical record
└── reference/ # Legacy docs, original specs
Conventions
Feature Folders
- Lowercase, hyphen-separated:
auth/, booking/, calendar-sync/
- Named by what the feature IS, not what it does:
auth not login
- Every feature folder has a
[feature]-overview.md at minimum (e.g., auth/auth-overview.md)
Status Markers
- 🟢 Implemented — working, documented, aligned
- 🟡 In Progress — partially built or partially documented
- 🔵 Not Started — documented but no code yet
- 🔴 Drifted — docs and code don't match (flagged by /arnold:check)
- ❓ Unknown — depends on an unresolved question
Source Provenance
Track where rules come from:
- (user-stated) — the human explicitly said this
- (domain-derived) — standard for this kind of application
- (Arnold-inferred) — Claude reasoned this should exist
- (decided) — deliberate team choice, links to decision record
- (code-derived) — extracted from reading the existing codebase
Decision Records
- Auto-numbered:
001-title.md, 002-title.md
- Include: date, who decided, what was chosen, what was rejected, consequences
- Once accepted, decisions are immutable (create a new one to supersede)
Unknowns
- Each question has an owner and a "decide by" date
- Bets include "risk if wrong" and "how we'll know"
- Resolved questions get moved to the relevant feature doc or a decision record
What Not to Do
- Don't create docs for trivial implementation details (variable names, import order)
- Don't update docs for every line of code — batch updates per feature
- Don't remove docs without explicit approval from the project owner
- Don't silently change rules — if a rule changes, note why
- Don't create a doc if the content fits naturally in an existing doc
Conventions
- Product requirements are tech-agnostic. Technical decisions live in
docs/spec.md.
- Feature overviews include acceptance criteria as a baseline, even before flows are written.
Arnold Commands
/arnold:init — scaffold docs/ for a new project/arnold:plan — generate or refine feature specs/arnold:check — compare docs to code, find drift/arnold:update — sync docs after a coding session/arnold:status — quick project overview/arnold:decide — record a decision in docs/decisions//arnold:resolve — fix drift items interactively/arnold:recap — start-of-session briefing/arnold:diff — quick drift scan/arnold:spec — decompose a spec document into feature-based docs/arnold:help — show all commands, when to use them, and doc structure/arnold:bug — record a structured bug report in docs/issues//arnold:milestone — define and track phased work with feature rollup/arnold:archive — move stale or reference docs to archive/reference folders/arnold:feature — feature completeness matrix, deep status, or deep plan/arnold:build — build code from docs with acceptance criteria verification/arnold:review — critique docs for usability, product, and technical issues
