Rustie Docs

Rustie Docs Skill

Documentation management for Rustie Method projects. Ensures docs are:

• In correct locations (agent-docs/ structure)
• Have proper frontmatter
• Not stale or broken
• Clearly marked as permanent or ephemeral

Quick Reference - All Modes

Documentation Structure

Allowed Locations

project-root/
├── README.md           ✅ Front door (required)
├── CLAUDE.md           ✅ AI instructions (optional)
├── CONTRIBUTING.md     ✅ Contribution guide (optional)
├── LICENSE.md          ✅ License (optional)
├── CHANGELOG.md        ✅ Changes (optional)
├── *.md                ❌ BLOCKED - must go in agent-docs/
│
└── agent-docs/
    ├── AI.md                   ✅ Required: How AI uses this repo
    ├── architecture.md         ✅ Required: System map
    ├── glossary.md             ✅ Optional: Domain terms
    │
    ├── features/               ✅ Feature documentation
    │   └── [feature]/
    │       ├── PRD.md          (permanent)
    │       ├── plan.md         (permanent until archived)
    │       ├── assumptions.md  (permanent until archived)
    │       ├── active-context.md (session)
    │       ├── sessions/       (ephemeral - archivable)
    │       ├── decisions/      (permanent ADRs)
    │       └── _ephemeral/     (auto-cleanable)
    │
    ├── decisions/adrs/         ✅ Global ADRs (permanent)
    ├── lessons/                ✅ Lessons learned (permanent)
    ├── instructions/           ✅ How-to guides (permanent)
    ├── reference/              ✅ Reference docs (permanent)
    ├── templates/              ✅ Doc templates (permanent)
    ├── archives/               ✅ Archived content
    └── _ephemeral/             ✅ Auto-cleanable scratch space

Document Lifecycles

Every doc in agent-docs/ MUST have a lifecycle: field in frontmatter:

Required Frontmatter

---
title: Document Title
lifecycle: permanent | session | ephemeral
created: YYYY-MM-DD
updated: YYYY-MM-DD
owner: feature-name | global
references:              # Optional: files this doc references
  - src/auth/index.ts
  - agent-docs/decisions/adrs/ADR-001.md
---

Mode: Audit

Triggers: "check docs", "audit docs", "audit documentation", "doc health"

Find issues in project documentation.

What Gets Checked

Steps

1. Run audit script:

   python3 ~/.claude/scripts/rustie-doc-audit.py
   

2. Parse results and categorize:

   • Errors (blocking - must fix)
   • Warnings (recommended fixes)
   • Info (suggestions)

3. Display report:

   RUSTIE DOCS AUDIT
   ═══════════════════════════════════════════════════════════════
   
   Scanned: 47 documents
   Issues: 8 found (3 errors, 5 warnings)
   
   ERRORS:
     [E1] agent-docs/features/auth/plan.md
          Missing lifecycle field in frontmatter
          Fix: Add "lifecycle: permanent" to frontmatter
   
     [E2] design-notes.md (in root)
          Should be in agent-docs/
          Fix: git mv design-notes.md agent-docs/reference/design-notes.md
   
   WARNINGS:
     [W1] agent-docs/features/auth/sessions/session-20251201/handoff.md
          28 days old - consider archiving
   
   AUTO-FIXABLE: 5 issues
   Run "/rustie-docs fix" to apply automatic fixes
   ═══════════════════════════════════════════════════════════════
   

4. Ask about fixes:

   • If errors found: "Would you like me to fix these issues?"
   • If only warnings: "No blocking issues. Archive old docs?"

Mode: Fix

Triggers: "fix docs", "clean docs", "fix documentation issues"

Auto-fix issues found during audit.

What Can Be Fixed Automatically

What Requires Manual Action

Steps

1. Run audit first (if not already run):

   python3 ~/.claude/scripts/rustie-doc-audit.py --json
   

2. Group fixable issues:

   • Frontmatter additions
   • File moves
   • Reference cleanups
   • Archive operations

3. For each fixable issue, apply fix:

   # Adding frontmatter
   # (prepend YAML block to file)
   
   # Moving files
   git mv old/path.md new/path.md
   
   # Archiving
   mkdir -p agent-docs/archives/ephemeral-$(date +%Y%m%d)
   git mv agent-docs/features/x/_ephemeral/* agent-docs/archives/ephemeral-$(date +%Y%m%d)/
   

4. Commit changes:

   git add agent-docs/
   git commit -m "docs: fix documentation issues (rustie-docs)"
   

5. Report results:

   RUSTIE DOCS FIX COMPLETE
   ═══════════════════════════════════════════════════════════════
   
   Fixed: 5 issues
     ✓ Added frontmatter to 2 files
     ✓ Moved 1 file from root to agent-docs/reference/
     ✓ Archived 2 old session directories
   
   Remaining: 3 issues (require manual action)
     • agent-docs/architecture.md may be stale (45 days)
     • agent-docs/reference/old-guide.md references deleted file
   
   ═══════════════════════════════════════════════════════════════
   

Mode: Create

Triggers: "create doc for X", "new doc", "add documentation for X"

Create new documentation in the correct location with proper structure.

Steps

1. Ask document type (use AskUserQuestion):

   What type of document?
   
   1. Feature PRD - Requirements for a new feature
   2. Feature Plan - Implementation plan with tasks
   3. ADR - Architecture Decision Record
   4. Lesson - Lessons learned from failure
   5. Reference - General reference documentation
   6. Subsystem README - Documentation for a code module
   7. Instruction/Checklist - How-to guide
   

2. Based on type, gather info:

   For Feature PRD/Plan:

   • Feature name
   • Create feature directory if needed
   • Copy from template

   For ADR:

   • Decision title
   • Feature-specific or global?
   • Get next ADR number

   For Lesson:

   • Lesson title
   • Severity (high/medium/low)
   • Trigger keywords

   For Subsystem README:

   • Module path (src/X/)
   • Module name
   • Dependencies

3. Create file with frontmatter:

   ---
   title: [Title]
   lifecycle: permanent
   created: [today]
   updated: [today]
   owner: [feature or global]
   ---
   

4. Apply appropriate template (from agent-docs/templates/)

5. Report:

   Created: agent-docs/features/auth/PRD.md
   
   Next steps:
   1. Fill in the [TODO] sections
   2. Run "/rustie-docs audit" to verify
   

Mode: Archive

Triggers: "archive docs", "archive old docs", "cleanup docs"

Move old ephemeral and session docs to archives.

What Gets Archived

Steps

1. Scan for archivable items:

   # Find old sessions
   find agent-docs -path "*sessions/*" -name "*.md" -mtime +7
   
   # Find old ephemeral
   find agent-docs -path "*_ephemeral/*" -mtime +7
   
   # Find completed features (100% in plan.md)
   

2. Display candidates:

   RUSTIE DOCS ARCHIVE
   ═══════════════════════════════════════════════════════════════
   
   Archivable items:
   
   SESSIONS (7+ days old):
     [1] features/auth/sessions/session-20251215/ (14 days)
     [2] features/auth/sessions/session-20251210/ (19 days)
   
   EPHEMERAL:
     [3] features/auth/_ephemeral/verify-reports/ (23 files)
     [4] _ephemeral/scratch/design-ideas.md (30 days)
   
   COMPLETED FEATURES:
     [5] features/user-onboarding/ (100% complete)
   
   Archive: [all / 1,2,3 / none]
   

3. Ask user (use AskUserQuestion):

   • All archivable items
   • Specific items (by number)
   • None (cancel)

4. Execute archiving:

   # Create dated archive folder
   archive_dir="agent-docs/archives/$(date +%Y%m%d)"
   mkdir -p "$archive_dir"
   
   # Move items
   git mv source "$archive_dir/"
   

5. Commit:

   git add agent-docs/
   git commit -m "docs: archive old documentation"
   

6. Report:

   Archived 5 items to agent-docs/archives/20251229/
   

Mode: Sync

Triggers: "sync docs", "update readme", "sync doc pointers"

Ensure README.md points to all documentation and check cross-references.

Steps

1. Scan agent-docs/ for all .md files

2. Build document map:

   Features: 4 features with docs
   ADRs: 12 decisions
   Lessons: 8 lessons
   Reference: 5 documents
   

3. Check README.md links:

   • Does it link to agent-docs/?
   • Are all major sections referenced?
   • Any broken links?

4. Generate suggested README section:

   ## Documentation
   
   | Doc | Purpose |
   |-----|---------|
   | [Architecture](agent-docs/architecture.md) | System design |
   | [Features](agent-docs/features/) | Current work (4 features) |
   | [Decisions](agent-docs/decisions/adrs/) | ADRs (12 decisions) |
   | [Lessons](agent-docs/lessons/) | Learned (8 lessons) |
   
   For AI agents, see [AI.md](agent-docs/AI.md).
   

5. Offer to update README:

   README.md documentation section is outdated.
   Update with current structure? [yes/no]
   

Frontmatter Templates

Permanent Document

---
title: Document Title
lifecycle: permanent
created: 2025-12-29
updated: 2025-12-29
owner: global
---

Session Document

---
title: Session Handoff - Feature Name
lifecycle: session
created: 2025-12-29
updated: 2025-12-29
owner: feature-name
session_id: session-20251229-143000
---

Ephemeral Document

---
title: Verify Report
lifecycle: ephemeral
created: 2025-12-29
expires_after_days: 7
owner: feature-name
---

ADR Document

---
title: "ADR-001: Use React for Frontend"
lifecycle: permanent
created: 2025-12-29
updated: 2025-12-29
owner: global
status: accepted
supersedes: null
superseded_by: null
---

Lesson Document

---
title: API Authentication Failures
lifecycle: permanent
created: 2025-12-29
updated: 2025-12-29
owner: global
severity: high
triggers:
  - API
  - authentication
  - 401
  - 403
---

Pre-Commit Hook Integration

This skill works with the doc commit hook (rustie-doc-commit-hook.sh):

# What the hook checks:
# 1. No .md in root except allowed list
# 2. All agent-docs/*.md have frontmatter
# 3. All frontmatter has lifecycle field

# If hook blocks:
# "Run /rustie-docs fix to resolve documentation issues"

The hook ensures enforcement at commit time, while this skill helps fix issues interactively.

Best Practices

DO

• Add frontmatter to every doc in agent-docs/
• Use _ephemeral/ for temporary files
• Run audit weekly or after major changes
• Archive old sessions promptly
• Keep README.md pointing to current structure

DON'T

• Create .md files in project root (except allowed list)
• Skip lifecycle field in frontmatter
• Let verify-reports accumulate indefinitely
• Ignore audit warnings for too long
• Manually edit frontmatter dates (use script)

Manual Invocation

/skill rustie-docs          # Prompts for mode
"check my docs"             # audit mode
"fix doc issues"            # fix mode
"create a new ADR"          # create mode
"archive old docs"          # archive mode
"sync readme"               # sync mode