Structured 6-pass forensic codebase analysis extracting scar tissue, defensive patterns, design tensions, golden paths, and tribal knowledge. Compresses findings into Prompt Fuel for expert-level agent prompts. Use when: creating domain-expert agents, investigating codebase quality, performing deep code archaeology, generating prompt fuel for agent prompts. Triggers: archaeology, forensic, scar tissue, domain knowledge extraction, prompt fuel.
6-pass forensic analysis framework that extracts domain expertise from codebases and compresses it into Prompt Fuel for agent prompts.
| # | Pass | Purpose | Automatable? | Typical Yield |
|---|---|---|---|---|
| 1 | Scar Tissue | Past bugs, regressions, defensive patterns born from production failures | Largely yes | 15-30 scars |
| 2 | Defensive Patterns | Guards, assertions, constraints, safety checks | Partially | 50-80 guards, 3-8 risks |
| 3 | Design Tensions |
| Structural conflicts, load-bearing jank, missing/premature abstractions |
| Partially |
| 10-20 tensions |
| 4 | Golden Paths | Best-in-class exemplars paired with anti-exemplars | Partially | 3-7 exemplars, 15-25 rules |
| 5 | Tribal Knowledge | Domain expert interview: fears, priorities, unwritten rules | No (interactive) | 10-15 nuggets |
| 6 | Synthesis | Compress passes 1-5 into per-agent Prompt Fuel | LLM-assisted | HANDOFF doc |
Pass 1 (Scar Tissue) ---+
|
Pass 2 (Defensive) -----+--> Pass 4 (Golden Paths) --+
| |
Pass 3 (Tensions) ------+ +--> Pass 6 (Synthesis)
|
Pass 5 (Tribal Knowledge) ----------------------------+
|
RITE-SPEC (agent definitions) -------------------------+
STANDARD mode (recommended): Execute Passes 1-4, then Pass 6. DEEP mode: Execute Passes 1-5 (including domain expert interview), then Pass 6.
For each pass: read the pass reference file, execute the search queries against the target codebase, categorize findings using the schema, and write output to .sos/wip/ARCHAEOLOGY/.
| Pass | Output Lines | Estimated Tokens | Notes |
|---|---|---|---|
| Pass 1 | 150-260 | ~2,500-3,500 | Scales with commit history depth |
| Pass 2 | 400-730 | ~5,000-8,500 | Scales with codebase LOC |
| Pass 3 | 150-240 | ~2,000-3,200 | Fewer entries but longer narratives |
| Pass 4 | 250-400 | ~3,500-5,200 | Includes code snippets |
| Pass 5 | 80-120 | ~1,000-1,500 | Interview transcript |
| Pass 6 | 250-400 | ~3,500-5,100 | Compression of all passes |
| Total | 1,280-2,150 | ~17,500-27,000 |
All archaeology artifacts are written to .sos/wip/ARCHAEOLOGY/:
.sos/wip/ARCHAEOLOGY/
PASS1-SCAR-TISSUE.md
PASS2-DEFENSIVE-PATTERNS.md
PASS3-DESIGN-TENSIONS.md
PASS4-GOLDEN-PATHS.md
PASS5-TRIBAL-KNOWLEDGE.md (only in DEEP mode)
HANDOFF-PROMPT-FUEL.md (Pass 6 output)
After rite creation, archive raw passes and commit only the HANDOFF as domain-knowledge.md in the rite's mena directory.
| Mode | Passes | Duration | Use Case |
|---|---|---|---|
| QUICK | Skip all | 0 | Rapid prototyping, familiar domains |
| STANDARD | 1-4 + 6 | 15-30 min | New rites with good codebase coverage |
| DEEP | 1-6 | 30-60 min | Critical domains, production-facing agents |
[SCAR-NNN] entry format[GUARD-NNN] entry format[TENSION-NNN] entry format[GOLD-NNN] entry format[TRIBAL-NNN] entry format