moicle 2.0.0 → 2.2.0

package/assets/skills/docs/sync/SKILL.md

@@ -5,583 +5,223 @@ description: Sync documentation workflow - reads codebase and docs folder to gen
 
 # Sync Docs Workflow
 
-Automated workflow that reads codebase and existing docs to generate a complete, structured documentation output with architecture overview, use case diagrams, and a README index linking all sub-files.
+Generate a complete `docs/` site (business overview, architecture, use cases with sequence diagrams, README index) from the current codebase. Includes a 3-iteration auto-review loop.
 
 ## When to use this skill
 
-- ✅ Need to (re)generate a whole `docs/` site from current codebase state
-- ✅ Existing docs have drifted from code and you want batch sync + review loop
-- ✅ Onboarding a project that has no structured docs at all
+- ✅ Re-generate the whole `docs/` site from current code
+- ✅ Existing docs have drifted; want batch sync with review loop
+- ✅ Project has no structured docs at all
 - ❌ Authoring a single doc by hand (README / API.md only) → use `/docs:write`
-- ❌ Need to understand the codebase, not document it → use `/research:onboarding`
-- ❌ Adding one new endpoint's doc only → use `/feature:api` Phase 4
+- ❌ Understand the codebase, not document it → use `/research:onboarding`
+- ❌ Adding doc for one endpoint → use `/feature:api` Phase 4
 
-## Workflow Overview
+## Read Architecture First
 
-```
-┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
-│ 1. SCAN  │──▶│1.5 CONFIRM──▶│2. GENERATE──▶│ 3. REVIEW │──▶│4. COMPLETE│
-└──────────┘   └──────────┘   └──────────┘   └──────────┘   └──────────┘
-                                    ▲              │
-                                    │   Feedback   │
-                                    └──────────────┘
-                                  (loop until pass)
-```
-
-**Key**: Phase 1.5 CONFIRM asks user to choose between REFACTOR (full restructure) or UPDATE (keep structure, update & link only). Phase 3 REVIEW automatically loops back to Phase 2 GENERATE if issues are found.
+Detect stack via `~/.claude/architecture/_shared/stack-detection.md`. Read `ddd-architecture.md` + stack doc.
 
 ---
 
-## Phase 1: SCAN
-
-**Goal**: Read and understand the entire codebase and existing docs
+## Workflow
 
-### Actions
-
-1. **Identify project stack**:
-   - Check `package.json`, `go.mod`, `pubspec.yaml`, `composer.json`, etc.
-   - Determine primary language and framework
+```
+SCAN → CONFIRM mode → GENERATE → REVIEW loop (≤3x) → COMPLETE
+```
 
-2. **Read existing documentation**:
-   ```bash
-   # Find all doc files
-   find . -name "*.md" -not -path "*/node_modules/*" -not -path "*/vendor/*" -not -path "*/.dart_tool/*" | sort
+`CONFIRM` asks the user to pick **REFACTOR** (full restructure of `docs/`) or **UPDATE** (keep existing structure, refresh content).
 
-   # Find existing docs folder
-   ls -la docs/ 2>/dev/null
-   ```
+---
 
-3. **Map codebase structure**:
-   ```bash
-   # Get directory tree (exclude build artifacts)
-   tree -L 4 -I 'node_modules|vendor|dist|build|.dart_tool|.git' --dirsfirst
-   ```
+## Phase 1: SCAN
 
-4. **Identify key components**:
-   - Entry points (main files, routes, controllers)
-   - Domain/business logic (services, use cases, models)
-   - Data layer (repositories, database, APIs)
-   - Configuration files
-   - Test files
+**Goal:** map codebase + existing docs in one pass.
 
-5. **Extract use cases** from the codebase:
-   - Read route definitions, controller methods, service methods
-   - Identify distinct user-facing features/flows
-   - Group related functionality into use cases
+```bash
+# Existing docs
+find . -name "*.md" -not -path "*/node_modules/*" -not -path "*/vendor/*" -not -path "*/.dart_tool/*" | sort
+ls docs/ 2>/dev/null
 
-6. **Read architecture files** (if exist):
-   ```bash
-   ls .claude/architecture/*.md 2>/dev/null
-   ls ~/.claude/architecture/*.md 2>/dev/null
-   ```
+# Code surface
+tree -L 4 -I 'node_modules|vendor|dist|build|.dart_tool|.git'
 
-### Output
-```markdown
-## Scan Results
-
-### Stack: [identified stack]
-### Architecture: [identified pattern]
-
-### Existing Docs
-- [list of existing .md files and their status]
-
-### Identified Use Cases
-1. [Use Case 1] - [brief description]
-2. [Use Case 2] - [brief description]
-3. [Use Case N] - [brief description]
-
-### Key Components
-- Entry Points: [list]
-- Business Logic: [list]
-- Data Layer: [list]
-- Config: [list]
-
-### Docs Output Plan
-- docs/README.md (index)
-- docs/business.md (business overview - non-technical, business language only)
-- docs/architecture.md
-- docs/use-cases/[usecase-name].md (per use case)
-- docs/diagrams/ (embedded in use case files via mermaid)
+# Entry points / use cases (per stack)
+# Go:       grep -r "func.*Handler" internal/
+# NestJS:   grep -r "@Controller\|@Get\|@Post" src/
+# Laravel:  cat routes/web.php routes/api.php
+# Remix:    ls app/routes/
+# Flutter:  grep -r "MaterialPageRoute\|GoRoute" lib/
 ```
 
+### Extract
+- Stack + framework
+- All domains / modules
+- All user-facing flows (endpoints / screens / commands)
+- Existing docs structure (if any)
+
 ### Gate
-- [ ] Codebase fully scanned
-- [ ] Use cases identified
-- [ ] Existing docs read
-- [ ] Output plan defined
+- [ ] Stack identified
+- [ ] All domains listed
+- [ ] All use cases listed (count + brief name)
+- [ ] Existing docs inventoried
 
 ---
 
 ## Phase 1.5: CONFIRM
 
-**Goal**: Ask the user how they want to handle docs before generating.
-
-### Actions
+Ask the user **explicitly** which mode:
 
-1. **Present scan results** from Phase 1 to the user (current structure, identified use cases, docs plan)
+| Mode | When to use | Effect |
+|------|-------------|--------|
+| **REFACTOR** | Existing docs are messy / partial / wrong structure | Restructure `docs/` from scratch, may delete old files |
+| **UPDATE** | Existing structure is fine, content is stale | Keep file paths + headings, refresh content + add missing sections |
 
-2. **Ask the user**:
-   ```
-   How would you like to proceed with the docs?
-
-   1. Refactor - Restructure docs into the standard template (docs/README.md, business.md, architecture.md, use-cases/) and relink everything
-   2. Update & Link only - Keep the current docs structure as-is, only update content and fix linking
-
-   (Choose 1 or 2)
-   ```
-
-3. **Based on the choice, set the mode for Phase 2**:
-   - **REFACTOR mode (choice 1)**: Run Phase 2 GENERATE in full - create new structure, migrate useful content from old docs into the new template, remove/replace old doc files that are no longer needed
-   - **UPDATE mode (choice 2)**: Run Phase 2 in update-only mode - preserve existing file/folder structure, only update content inside existing files to match current code, add/fix links between files, add mermaid diagrams where missing, DO NOT move/rename/delete existing files
+If the user is unsure: default to **UPDATE** (less destructive).
 
 ### Gate
-- [ ] User has chosen a mode (REFACTOR or UPDATE)
-- [ ] Mode is recorded for Phase 2 to handle accordingly
+- [ ] User confirmed mode
+- [ ] If REFACTOR: explicit OK to remove old files
 
 ---
 
 ## Phase 2: GENERATE
 
-**Goal**: Generate all documentation files based on the selected mode from Phase 1.5
-
-### Mode Selection
+**Goal:** produce the target `docs/` tree.
 
-- **REFACTOR mode**: Create an entirely new docs structure following the template below. If old docs exist, migrate useful content into the new structure. May remove/replace old files.
-- **UPDATE mode**: Preserve the existing file/folder structure. Only perform:
-  - Update content in existing doc files to match current code
-  - Add/fix links between files (relative links)
-  - Add mermaid diagrams to existing files where missing
-  - Add new files ONLY when there are undocumented use cases/features
-  - DO NOT move, rename, or delete existing files
-  - Ensure there is 1 index file (README.md or existing index) linking to all docs
-
-> **The templates below apply fully to REFACTOR mode. For UPDATE mode, use them as content/format reference only — do NOT force the structure.**
-
-### Output Structure
+### Target structure (REFACTOR mode)
 
 ```
 docs/
-├── README.md                    # Index - links to all sub-files
-├── business.md                  # Business overview - non-technical, business language only
-├── architecture.md              # Architecture overview + system diagram
-└── use-cases/
-    ├── [use-case-1].md          # Use case doc + sequence diagram
-    ├── [use-case-2].md          # Use case doc + sequence diagram
-    └── [use-case-N].md          # Use case doc + sequence diagram
-```
-
-### 2.1 Generate `docs/README.md` (Index)
-
-```markdown
-# [Project Name] Documentation
-
-> Auto-generated documentation synced from codebase.
-
-## Overview
-
-[1-2 paragraph project description derived from codebase]
-
-## Table of Contents
-
-### Business
-- [Business Overview](./business.md) - Business overview, goals, target users
-
-### Architecture
-- [Architecture Overview](./architecture.md) - System architecture, layers, and patterns
-
-### Use Cases
-- [Use Case 1](./use-cases/use-case-1.md) - [brief description]
-- [Use Case 2](./use-cases/use-case-2.md) - [brief description]
-- [Use Case N](./use-cases/use-case-n.md) - [brief description]
-
-## Tech Stack
-
-| Component | Technology |
-|-----------|-----------|
-| Language | [language] |
-| Framework | [framework] |
-| Database | [database] |
-| Other | [key deps] |
-
-## Quick Links
-
-- [Business Overview](./business.md)
-- [Architecture Diagram](./architecture.md#system-diagram)
-- [Use Case Diagrams](./use-cases/)
-```
-
-### 2.2 Generate `docs/business.md` (Business Overview)
-
-This file is written entirely in business language. NO code, NO class/function names, NO technical jargon. Target audience: stakeholders, product owners, business analysts - people who don't need to know the code.
-
-```markdown
-# [Project Name] - Business Overview
-
-## What is this product?
-
-[2-3 paragraphs describing the product in everyday language. Explain what problem it solves, for whom, and why it's needed.]
-
-## Target Users
-
-### [Role 1] - e.g., End User
-- **Who**: [description]
-- **Needs**: [what they need from the product]
-- **What they do**: [key actions on the system]
-
-### [Role 2] - e.g., Administrator
-- **Who**: [description]
-- **Needs**: [what they need]
-- **What they do**: [key actions on the system]
-
-## Core Business Processes
-
-### [Process 1] - e.g., Registration and first-time use
-[Describe each step from the user's perspective. No mention of API, database, or any technical details.]
-
-1. [Step 1 - what the user does]
-2. [Step 2 - how the system responds]
-3. [Step N]
-
-### [Process 2] - e.g., Placing an order
-[Same approach - describe from a business perspective]
-
-## Key Features
-
-| Feature | Description | Used by |
-|---------|-------------|---------|
-| [Feature 1] | [explain in business language] | [role] |
-| [Feature 2] | [explain] | [role] |
-
-## Business Rules
-
-Key rules the system follows:
-
-1. **[Rule 1]**: [explain - e.g., "Every order must contain at least 1 product"]
-2. **[Rule 2]**: [explain - e.g., "Users can only request a refund within 7 days"]
-3. **[Rule N]**: [explain]
-
-## Business Entity Relationships
-
-[Describe key relationships in plain text, e.g.:]
-- A **customer** can create multiple **orders**
-- An **order** contains multiple **products**
-- A **product** belongs to a **category**
-
-## Value Flow
-
-[Describe how the product creates value for each stakeholder:]
-
-- **For [role 1]**: [value they receive]
-- **For [role 2]**: [value they receive]
-- **For the business**: [value the business receives]
-
-## Business Glossary
-
-| Term | Definition |
-|------|-----------|
-| [Term 1] | [explain in the product's context] |
-| [Term 2] | [explain] |
-```
-
-**IMPORTANT rules for business.md**:
-- DO NOT use words like: API, endpoint, database, repository, controller, service, model, schema, query, migration, route, middleware, component, module, class, function, method, interface, type
-- NO code blocks whatsoever
-- NO file path references or code file names
-- Write as if explaining to someone who doesn't know programming
-- Use the project's business domain language (e.g., "order" instead of "Order entity", "user" instead of "User model")
-- Extract business rules from code logic (validation, conditions, constraints) and express them in business language
-
-### 2.3 Generate `docs/architecture.md` (Technical)
-
-```markdown
-# Architecture Overview
-
-## System Diagram
-
-\`\`\`mermaid
-graph TB
-    [Generate actual system architecture diagram based on codebase layers]
-\`\`\`
-
-## Layers
-
-### [Layer 1 Name]
-- **Location**: `[directory path]`
-- **Responsibility**: [what this layer does]
-- **Key Files**: [list important files]
-
-### [Layer 2 Name]
-[same structure]
-
-## Directory Structure
-
-\`\`\`
-[actual project directory tree with annotations]
-\`\`\`
-
-## Dependencies Between Layers
-
-\`\`\`mermaid
-graph LR
-    [Show dependency direction between layers]
-\`\`\`
-
-## Design Patterns Used
-- [Pattern 1]: [where and why]
-- [Pattern 2]: [where and why]
-
-## Data Flow
-
-\`\`\`mermaid
-flowchart LR
-    [Show how data flows through the system]
-\`\`\`
-```
-
-### 2.4 Generate Use Case Files (`docs/use-cases/[name].md`)
-
-Generate ONE file per use case:
-
-```markdown
-# [Use Case Name]
-
-## Overview
-
-[Description of what this use case does from user perspective]
-
-## Actors
-- [Actor 1]: [role]
-- [Actor 2]: [role]
-
-## Flow
-
-### Main Flow
-
-1. [Step 1]
-2. [Step 2]
-3. [Step N]
-
-### Sequence Diagram
-
-\`\`\`mermaid
-sequenceDiagram
-    participant [Actor]
-    participant [Component1]
-    participant [Component2]
-    participant [DataStore]
-
-    [Actor]->>[Component1]: [action]
-    [Component1]->>[Component2]: [action]
-    [Component2]->>[DataStore]: [action]
-    [DataStore]-->>[Component2]: [response]
-    [Component2]-->>[Component1]: [response]
-    [Component1]-->>[Actor]: [response]
-\`\`\`
-
-## Related Files
-
-| File | Purpose |
-|------|---------|
-| `[path/to/file]` | [what it does in this use case] |
-| `[path/to/file]` | [what it does in this use case] |
-
-## Error Cases
-
-| Error | Cause | Handling |
-|-------|-------|----------|
-| [Error 1] | [cause] | [how handled] |
-
-## Notes
-
-- [Any important implementation details]
-```
-
-### Generation Rules
-
-1. **Diagrams MUST be mermaid** - embedded in markdown, not external files
-2. **Every use case MUST have a sequence diagram** showing the actual flow through code
-3. **Architecture MUST have a system diagram** showing layers/components
-4. **README MUST link to every sub-file** with working relative links
-5. **Use actual file paths** from codebase, not placeholders
-6. **Use actual class/function names** from codebase
-7. **If existing docs/ folder has content**, merge/update rather than overwrite useful information
+├── README.md              # Index linking to everything below
+├── business.md            # WHAT the system does, for non-engineers
+├── architecture.md        # HOW it's structured (layers + domains + tech)
+├── use-cases/
+│   ├── README.md          # Index of use cases
+│   ├── <use-case-1>.md    # One file per user-facing flow, with sequence diagram
+│   └── ...
+├── api.md                 # If service has external API
+└── runbook.md             # How to run / deploy / debug
+```
+
+### File rules
+
+**`docs/README.md`** — index only (≤30 lines).
+- One-line description, link to each sub-doc, last-updated timestamp.
+
+**`docs/business.md`** — for non-engineers.
+- NO API endpoints, NO code blocks, NO file paths
+- Cover: what problem this solves, who uses it, key user journeys (named like a PRD), success metrics
+- Plain language, no jargon
+
+**`docs/architecture.md`** — for engineers.
+- Layer diagram (mermaid)
+- Domain list with 1-line responsibility
+- Cross-domain communication pattern
+- Tech decisions (DB, queue, cache, auth — with rationale)
+- Link to `~/.claude/architecture/<stack>.md` for layer rules
+
+**`docs/use-cases/<name>.md`** — one per flow.
+- Trigger (who, what action)
+- Preconditions
+- Sequence diagram (mermaid `sequenceDiagram`) showing actor → handler → usecase → infra → response
+- Postconditions / side effects (events raised, notifications sent)
+- Errors (each with HTTP code + meaning)
+
+**`docs/api.md`** — only if external API exists.
+- Auth, base URL, error format, pagination — then endpoint table
+- For deep API ref, link to OpenAPI spec
+
+**`docs/runbook.md`** — for ops / on-call.
+- Local dev (≤5 commands)
+- Deploy steps
+- Common failures + how to recover
+- Monitoring dashboards + log queries
+
+### Mermaid rules
+
+- Sequence diagrams for use cases
+- Class diagrams only when ER is non-obvious
+- Validate syntax: `mermaid-cli` if available, otherwise eyeball test
+- ≤7 actors per sequence (split if more)
 
 ### Gate
-- [ ] docs/README.md generated with all links
-- [ ] docs/business.md generated with pure business language (no technical terms)
-- [ ] docs/architecture.md generated with system diagram
-- [ ] All use case files generated with sequence diagrams
-- [ ] All links are relative and correct
-- [ ] All diagrams use mermaid syntax
+- [ ] All target files written
+- [ ] business.md has zero code / endpoints
+- [ ] Every use case has a sequence diagram
+- [ ] README.md links to every file
+- [ ] All file paths in docs resolve (no broken references)
 
 ---
 
-## Phase 3: REVIEW (Automated Loop)
-
-**Goal**: Verify generated docs are complete and accurate. Loop back to GENERATE if issues found.
+## Phase 3: REVIEW LOOP (≤3 iterations)
 
-### Review Checklist
+**Goal:** auto-check + fix until docs pass.
 
-Run through ALL checks below. If ANY check fails, fix and re-check.
+For each iteration:
 
-#### 3.1 Structure Check
-- [ ] `docs/README.md` exists and has all links
-- [ ] `docs/business.md` exists
-- [ ] `docs/architecture.md` exists with system diagram
-- [ ] Each identified use case has its own file in `docs/use-cases/`
-- [ ] All relative links in README.md point to existing files
+### 3.1 Structure
+- [ ] All target files exist
+- [ ] README.md links resolve
+- [ ] No duplicate content across files
 
-#### 3.2 Business Check
-- [ ] `docs/business.md` contains NO technical jargon (API, endpoint, database, repository, controller, service, model, schema, query, migration, route, middleware, component, module, class, function, method, interface, type)
-- [ ] `docs/business.md` has NO code blocks
-- [ ] `docs/business.md` does NOT reference file paths
-- [ ] Business processes are fully described from the user's perspective
-- [ ] Business rules are correctly extracted from code logic
-- [ ] Glossary contains all domain-specific terms
+### 3.2 Business
+- [ ] business.md uses plain language (no `API`, `JSON`, `class`, file paths)
+- [ ] business.md covers all top-level user journeys
 
-#### 3.3 Content Check
-- [ ] Architecture diagram reflects actual codebase layers
-- [ ] Each use case sequence diagram matches actual code flow
-- [ ] File paths referenced in docs actually exist in codebase
-- [ ] Class/function names in diagrams match actual code
-- [ ] No placeholder text like `[TODO]`, `[TBD]`, `[placeholder]`
-- [ ] No template markers like `{name}`, `[name]` left unfilled
+### 3.3 Architecture
+- [ ] Layer diagram matches actual code structure
+- [ ] Every code domain has a row in domain table
 
-#### 3.4 Completeness Check
-- [ ] Every major feature/flow has a use case doc
-- [ ] Architecture doc covers all layers found in codebase
-- [ ] README links to ALL generated sub-files
-- [ ] Diagrams are syntactically valid mermaid
+### 3.4 Use cases
+- [ ] One file per identified use case (Phase 1)
+- [ ] Each has trigger / preconditions / sequence / postconditions / errors
+- [ ] Sequence diagrams render
 
-#### 3.5 Consistency Check
-- [ ] Naming is consistent across all docs
-- [ ] Same component uses same name everywhere
-- [ ] File naming convention is consistent (kebab-case)
+### 3.5 Consistency
+- [ ] Same terminology everywhere (e.g., "domain" vs "module")
+- [ ] No file paths referenced that don't exist
+- [ ] No endpoints referenced that don't exist in code
 
-### Review Process
-
-```
-FOR each check in checklist:
-  IF check FAILS:
-    1. Note the issue
-    2. Fix it (go back to relevant GENERATE sub-step)
-    3. Re-run ALL checks from the beginning
-  IF all checks PASS:
-    Proceed to Phase 4
-```
-
-### Review Output
-```markdown
-## Review Results - Iteration [N]
-
-### Checks Passed: [X/total]
-### Checks Failed: [Y/total]
-
-### Issues Found
-1. [issue] → [fix applied]
-2. [issue] → [fix applied]
-
-### Status: [PASS - proceed to Phase 4 / FAIL - re-running Phase 2]
-```
-
-**IMPORTANT**: Do NOT proceed to Phase 4 until ALL checks pass. Maximum 3 iterations - if still failing after 3 loops, report remaining issues and proceed.
+### Loop
+- If any check fails → fix that section, restart the relevant subset of checks
+- Max 3 iterations; if still failing → report what's blocking + ask user
 
 ---
 
 ## Phase 4: COMPLETE
 
-**Goal**: Final output and summary
-
-### Actions
-
-1. **List all generated files**:
-   ```bash
-   find docs/ -name "*.md" | sort
-   ```
-
-2. **Print summary**:
-   ```markdown
-   ## Sync Docs Complete
-
-   ### Generated Files
-   - docs/README.md (index)
-   - docs/business.md (business overview)
-   - docs/architecture.md
-   - docs/use-cases/[list all]
-
-   ### Use Cases Documented: [count]
-   ### Diagrams Generated: [count]
-   ### Review Iterations: [count]
-
-   ### How to Use
-   Start at `docs/README.md` - it links to everything.
-   ```
-
-3. **Read the docs/ folder one final time** to confirm everything is in order
-
-### Gate
-- [ ] All files verified
-- [ ] Summary provided
-- [ ] User informed of output location
-
----
-
-## Recommended Agents
+```markdown
+## Docs Sync Complete
 
-| Phase | Agent | Purpose |
-|-------|-------|---------|
-| SCAN | `@clean-architect` | Identify architecture patterns |
-| SCAN | `@code-reviewer` | Understand code structure |
-| GENERATE | `@docs-writer` | Write documentation |
-| REVIEW | `@code-reviewer` | Verify accuracy |
+### Mode: {REFACTOR / UPDATE}
 
----
+### Files
+- Created: {N}
+- Updated: {N}
+- Deleted: {N — REFACTOR mode only}
 
-## Quick Reference
+### Coverage
+- Domains documented: {N/N}
+- Use cases documented: {N/N}
+- Diagrams: {N}
 
-### Trigger Phrases
-- "sync docs"
-- "sync documentation"
-- "generate structured docs"
-- "update docs sync"
-- "create docs from codebase"
-- "doc sync"
+### Review iterations: {1/2/3}
 
-### Output Structure
-```
-docs/
-├── README.md          # Index with links
-├── business.md        # Business overview (non-technical)
-├── architecture.md    # System overview + diagram
-└── use-cases/
-    └── *.md           # One per use case + sequence diagram
+### Next steps for the team
+- Review `docs/business.md` with product
+- Validate `docs/use-cases/*.md` flows with team leads
+- Set up doc lint in CI (broken-link checker)
 ```
 
-### Diagram Types Used
-| Where | Diagram Type | Purpose |
-|-------|-------------|---------|
-| architecture.md | `graph TB` | System architecture |
-| architecture.md | `graph LR` | Layer dependencies |
-| architecture.md | `flowchart LR` | Data flow |
-| use-cases/*.md | `sequenceDiagram` | Use case flow |
-
-### Review Loop
-```
-Scan → Confirm (Refactor/Update?) → Generate → Review → Pass? → Complete
-                                                      → Fail? → Fix → Review again (max 3x)
-```
+---
 
-## Success Criteria
+## Hard Rules
 
-Documentation sync is complete when:
-1. Business overview written entirely in business language, no technical jargon
-2. All codebase features are documented as use cases
-3. Architecture accurately reflects codebase
-4. Every use case has a sequence diagram
-5. README.md links to all sub-files
-6. All file paths and names match actual codebase
-7. All mermaid diagrams are valid
-8. Review loop passed all checks
+- **business.md is for humans** — strip jargon, no code, no file paths
+- **architecture.md links to canonical rules**, doesn't duplicate them
+- **One use case per file** — easier to update, easier to review
+- **Mermaid only if it renders** — broken diagrams worse than no diagrams
+- **REFACTOR mode requires explicit user OK** — never delete docs without confirmation
+- **Max 3 review iterations** — beyond that, the prompt or scope is the problem, not the docs
 
 ---
 
@@ -589,17 +229,17 @@ Documentation sync is complete when:
 
 | When | Use |
 |------|-----|
-| Authoring a single doc by hand | `/docs:write` |
-| Onboarding self / a new dev to the project | `/research:onboarding` |
-| Adding only an endpoint's doc | `/feature:api` Phase 4 |
-| The architecture itself needs a review | `/review:architect` |
+| Author single doc by hand | `/docs:write` |
+| Onboard self / new dev | `/research:onboarding` |
+| Doc only one new endpoint | `/feature:api` Phase 4 |
+| Architecture itself needs review | `/review:architect` |
 
 ## Recommended Agents
 
 | Phase | Agent | Purpose |
 |-------|-------|---------|
-| SCAN | `@clean-architect` | Identify domains and patterns |
+| SCAN | `@clean-architect` | Identify domains + patterns |
 | GENERATE | `@docs-writer` | Write all doc files |
 | GENERATE | `@api-designer` | API reference accuracy |
-| GENERATE | `@db-designer` | Data model doc |
-| REVIEW | `@code-reviewer` | Verify code references resolve |
+| GENERATE | `@db-designer` | Data model accuracy |
+| REVIEW | `@code-reviewer` | Verify code refs resolve |