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 & Lessons

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

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/lessons/ — Portable Lessons Learned

General lessons 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:

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. lessons/ 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)

FLOW 16 DOCUMENT and the workflow tracker

In Silver Bullet's composable flows architecture, documentation maps to two distinct artifacts and one dedicated path:

• FLOW 16 DOCUMENT — runs post-ship. Steps include gsd:docs-update, engineering:documentation, engineering:tech-debt, gsd:milestone-summary when needed, conversation memory capture when available, and gsd:session-report when needed. Produces updated docs/ and session log. This is what triggers the Documentation Scheme described on this page.
• 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 the active path, completed paths, deferred improvements, dynamic insertions, 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.

FLOW 16 is what populates the project-level docs described in this page. The per-instance workflow tracker is what gives visibility into the ongoing composition before FLOW 16 runs.

See Also

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