Documentation Scheme

Overview

Every Silver Bullet project gets a documentation architecture scaffolded by /silver:init. The scheme is designed around three principles:

• Docs are artifacts, not afterthoughts — every document is produced by a specific workflow step and reviewed by the artifact reviewer framework
• No doc grows unbounded — every file uses one of five scalability patterns with enforced size caps
• Separation of concerns — planning artifacts (.planning/) are ephemeral per-milestone; project docs (docs/) are durable across milestones

Three Layers

Documentation lives in three distinct layers, each with its own audience and lifespan:

Scalability Patterns

Every growing document uses one of these bounded patterns to prevent unbounded file growth:

Core Files

These files are scaffolded by /silver:init and form the backbone of your project documentation:

Knowledge & Learnings

Project intelligence is split into two directories to separate project-specific knowledge from portable learnings.

docs/knowledge/ — Project-Scoped Intelligence

Things learned about this project: architecture patterns discovered, gotchas encountered, key decisions made, recurring patterns, and open questions. Not redundant with ARCHITECTURE.md (which captures current state, not journey) or phase CONTEXT.md files (which are single-phase and archived).

• File convention: YYYY-MM.md — one file per month, append-only within that month, frozen after
• Categories: Architecture Patterns, Known Gotchas, Key Decisions, Recurring Patterns, Open Questions
• Gateway: knowledge/INDEX.md lists all project docs with paths and purposes

docs/learnings/ — Portable Learnings

General learnings applicable beyond this project. Written as if explaining to someone who has never seen this codebase. No project-specific file paths, feature names, or requirement IDs.

• File convention: YYYY-MM.md — same monthly segmentation
• Category taxonomy:

Graphify Retrieval

Graphify is Silver Bullet's preferred project-memory retrieval layer. After /silver:init, SB expects Graphify to be available so agents can query the local knowledge graph before work that benefits from project context: planning, editing, debugging, review, documentation, shipping, and release.

The no-key refresh path builds a local graph from the repository without semantic LLM extraction:

Agents should query with concrete task and file context, then inspect the returned nodes before acting. Broad words can match workflow or documentation nodes first, so the useful query usually names the current file, hook, skill, or artifact type.

If Graphify is missing, stale, or returns no relevant context, SB falls back to direct reads of docs/knowledge/INDEX.md, the current monthly docs/knowledge/YYYY-MM.md, the current monthly docs/learnings/YYYY-MM.md, and any directly referenced project docs. That fallback is degraded behavior: it preserves correctness, but Graphify remains the required default for SB-activated projects.

graphify-out/ and raw/ are generated local state and are ignored by default. Full semantic extraction and optional surfaces such as MCP or database-backed storage can be enabled separately when the project has the required keys and services.

Token Compression (RTK + Context Mode)

RTK (recommended_tools.rtk) compresses shell command output via upstream PreToolUse hooks once rtk-ai/rtk is installed and wired. Context Mode (recommended_tools.context_mode) compacts MCP results and recovers session state across compaction; it is ELv2-licensed and highest value with MCP-heavy workflows.

Both tools are separate opt-ins from Graphify and agentmemory. SB install gates verify CLI and host wiring; usage rules (when to use ctx_* vs Read) live in silver-bullet.md §2g-ii. Verify with bash scripts/enable-rtk-context-mode.sh. See docs/RTK.md and docs/CONTEXT-MODE.md.

Optional Files

Created when your project needs them — not scaffolded by default:

Size Caps

Every document has an enforced growth limit. The artifact reviewer flags violations during review rounds.

When Docs Update

Non-Redundancy Rules

Silver Bullet enforces strict non-redundancy across all documentation layers:

1. .planning/ artifacts are the source of truth during active development — docs/ files are derived summaries
2. knowledge/ captures intelligence not derivable from code or git history
3. learnings/ captures portable learnings — never duplicates project-specific knowledge
4. ARCHITECTURE.md is high-level design only — detailed phase designs stay in .planning/phases/
5. CHANGELOG.md is the task log — git log is the commit log (different granularity, no overlap)

AF-DOCUMENT and the workflow tracker

In Silver Bullet's v0.48.3 APO architecture, documentation maps to catalog atomic flows, durable project docs, and the per-instance workflow tracker:

• AF-DOCUMENT — runs when durable documentation, handoff, content, retro, or knowledge-capture evidence is required. Steps include silver:ensure-docs, technical debt capture when needed, SB milestone summary when needed, conversation memory capture when available, and SB session reporting when needed.
• Per-instance workflow tracker — the real-time state tracking artifact for an active composition. Created when a composition begins, updated after every path completes. Records selected catalog atoms, completed paths, deferred improvements, dynamic insertions, V-loop/evidence status, and the full composition plan. Unlike the three-layer documentation scheme (which is project-level and durable), .planning/workflows/<id>.md is composition-level and ephemeral — it exists for the duration of the current chain. The retired single-file WORKFLOW.md model is legacy only.

AF-DOCUMENT is what populates the project-level docs described in this page. The per-instance workflow tracker gives visibility into the ongoing composition before durable docs are updated.

See Also

• Composable Workflow Orchestration — AF-DOCUMENT in the canonical APO catalog and the per-instance workflow tracker
• Core Concepts — skills, hooks, enforcement layers, and the full mental model
• Verification Before Completion — how silver:verify enforces quality gates
• Dev Workflow — the full development cycle, including the Documentation finalization step