Using System Archaeologist

System Archaeologist - Codebase Architecture Analysis

Overview

Analyze existing codebases through coordinated subagent exploration to produce comprehensive architecture documentation with C4 diagrams, subsystem catalogs, and architectural assessments.

Core principle: Systematic archaeological process with quality gates prevents rushed, incomplete analysis.

When to Use

• User requests architecture documentation for existing codebase
• Need to understand unfamiliar system architecture
• Creating design docs for legacy systems
• Analyzing codebases of any size (small to large)
• User mentions: "analyze codebase", "architecture documentation", "system design", "generate diagrams"

Mandatory Workflow

Step 1: Create Workspace (NON-NEGOTIABLE)

Before any analysis:

mkdir -p docs/arch-analysis-$(date +%Y-%m-%d-%H%M)/temp

Why this is mandatory:

• Organizes all analysis artifacts in one location
• Enables subagent handoffs via shared documents
• Provides audit trail of decisions
• Prevents file scatter across project

Common rationalization: "This feels like overhead when I'm pressured"

Reality: 10 seconds to create workspace saves hours of file hunting and context loss.

Step 2: Write Coordination Plan

Immediately after workspace creation, write 00-coordination.md:

## Analysis Plan
- Scope: [directories to analyze]
- Strategy: [Sequential/Parallel with reasoning]
- Time constraint: [if any, with scoping plan]
- Complexity estimate: [Low/Medium/High]

## Execution Log
- [timestamp] Created workspace
- [timestamp] [Next action]

Why coordination logging is mandatory:

• Documents strategy decisions (why parallel vs sequential?)
• Tracks what's been done vs what remains
• Enables resumption if work is interrupted
• Shows reasoning for future review

Common rationalization: "I'll just do the work, documentation is overhead"

Reality: Undocumented work is unreviewable and non-reproducible.

Step 3: Holistic Assessment First

Before diving into details, perform systematic scan:

1. Directory structure - Map organization (feature? layer? domain?)
2. Entry points - Find main files, API definitions, config
3. Technology stack - Languages, frameworks, dependencies
4. Subsystem identification - Identify 4-12 major cohesive groups

Write findings to 01-discovery-findings.md

Why holistic before detailed:

• Prevents getting lost in implementation details
• Identifies parallelization opportunities
• Establishes architectural boundaries
• Informs orchestration strategy

Common rationalization: "I can see the structure, no need to document it formally"

Reality: What's obvious to you now is forgotten in 30 minutes.

Step 4: Subagent Orchestration Strategy

Decision point: Sequential vs Parallel

Use SEQUENTIAL when:

• Project < 5 subsystems
• Subsystems have tight interdependencies
• Quick analysis needed (< 1 hour)

Use PARALLEL when:

• Project ≥ 5 independent subsystems
• Large codebase (20K+ LOC, 10+ plugins/services)
• Subsystems are loosely coupled

Document decision in 00-coordination.md:

## Decision: Parallel Analysis
- Reasoning: 14 independent plugins, loosely coupled
- Strategy: Spawn 14 parallel subagents, one per plugin
- Estimated time savings: 2 hours → 30 minutes

Common rationalization: "Solo work is faster than coordination overhead"

Reality: For large systems, orchestration overhead (5 min) saves hours of sequential work.

Step 5: Subagent Delegation Pattern

When spawning subagents for analysis:

Create task specification in temp/task-[subagent-name].md:

## Task: Analyze [specific scope]
## Context
- Workspace: docs/arch-analysis-YYYY-MM-DD-HHMM/
- Read: 01-discovery-findings.md
- Write to: 02-subsystem-catalog.md (append your section)

## Expected Output
Follow contract in documentation-contracts.md:
- Subsystem name, location, responsibility
- Key components (3-5 files/classes)
- Dependencies (inbound/outbound)
- Patterns observed
- Confidence level

## Validation Criteria
- [ ] All contract sections complete
- [ ] Confidence level marked
- [ ] Dependencies bidirectional (if A depends on B, B shows A as inbound)

Why formal task specs:

• Subagents know exactly what to produce
• Reduces back-and-forth clarification
• Ensures contract compliance
• Enables parallel work without conflicts

Step 6: Validation Gates (MANDATORY)

After EVERY major document is produced, validate before proceeding.

What "validation gate" means:

• Systematic check against contract requirements
• Cross-document consistency verification
• Quality gate before proceeding to next phase
• NOT just "read it again" - use a checklist

Two validation approaches:

A) Separate Validation Subagent (PREFERRED)

• Spawn dedicated validation subagent
• Agent reads document + contract, produces validation report
• Provides "fresh eyes" review
• Use when: Time allows (5-10 min overhead), complex analysis, multiple subsystems

B) Systematic Self-Validation (ACCEPTABLE)

• You validate against contract checklist systematically
• Document your validation in coordination log
• Use when: Tight time constraints (< 1 hour), simple analysis, solo work already
• MUST still be systematic (not "looks good")

Validation checklist (either approach):

• Contract compliance (all required sections present)
• Cross-document consistency (subsystems in catalog match diagrams)
• Confidence levels marked
• No placeholder text ("[TODO]", "[Fill in]")
• Dependencies bidirectional (A→B means B shows A as inbound)

When using self-validation, document in coordination log:

## Validation Decision - [timestamp]
- Approach: Self-validation (time constraint: 1 hour deadline)
- Documents validated: 02-subsystem-catalog.md
- Checklist: Contract ✓, Consistency ✓, Confidence ✓, No placeholders ✓
- Result: APPROVED for diagram generation

Validation status meanings:

• APPROVED → Proceed to next phase
• NEEDS_REVISION (warnings) → Fix non-critical issues, document as tech debt, proceed
• NEEDS_REVISION (critical) → BLOCK. Fix issues, re-validate. Max 2 retries, then escalate to user.

Common rationalization: "Validation slows me down"

Reality: Validation catches errors before they cascade. 2 minutes validating saves 20 minutes debugging diagrams generated from bad data.

Common rationalization: "I already checked it, validation is redundant"

Reality: "Checked it" ≠ "validated systematically against contract". Use the checklist.

Step 7: Handle Validation Failures

When validator returns NEEDS_REVISION with CRITICAL issues:

1. Read validation report (temp/validation-*.md)
2. Identify specific issues (not general "improve quality")
3. Spawn original subagent again with fix instructions
4. Re-validate after fix
5. Maximum 2 retries - if still failing, escalate: "Having trouble with [X], need your input"

DO NOT:

• Proceed to next phase despite BLOCK status
• Make fixes yourself without re-spawning subagent
• Rationalize "it's good enough"
• Question validator authority ("validation is too strict")

From baseline testing: Agents WILL respect validation when it's clear and authoritative. Make validation clear and authoritative.

Working Under Pressure

Time Constraints Are Not Excuses to Skip Process

Common scenario: "I need this in 3 hours for a stakeholder meeting"

WRONG response: Skip workspace, skip validation, rush deliverables

RIGHT response: Scope appropriately while maintaining process

Example scoping for 3-hour deadline:

## Coordination Plan
- Time constraint: 3 hours until stakeholder presentation
- Strategy: SCOPED ANALYSIS with quality gates maintained
- Timeline:
  - 0:00-0:05: Create workspace, write coordination plan (this)
  - 0:05-0:35: Holistic scan, identify all subsystems
  - 0:35-2:05: Focus on 3 highest-value subsystems (parallel analysis)
  - 2:05-2:35: Generate minimal viable diagrams (Context + Component only)
  - 2:35-2:50: Validate outputs
  - 2:50-3:00: Write executive summary with EXPLICIT limitations section

## Limitations Acknowledged
- Only 3/14 subsystems analyzed in depth
- No module-level dependency diagrams
- Confidence: Medium (time-constrained analysis)
- Recommend: Full analysis post-presentation

Key principle: Scoped analysis with documented limitations > complete analysis done wrong.

Handling Sunk Cost (Incomplete Prior Work)

Common scenario: "We started this analysis last week, finish it"

Checklist:

1. Find existing workspace - Look in docs/arch-analysis-*/
2. Read coordination log - Understand what was done and why stopped
3. Assess quality - Is prior work correct or flawed?
4. Make explicit decision:
   • Prior work is good → Continue from where it left off, update coordination log
   • Prior work is flawed → Archive old workspace, start fresh, document why
   • Prior work is mixed → Salvage good parts, redo bad parts, document decisions

DO NOT assume prior work is correct just because it exists.

Update coordination log:

## Incremental Work - [date]
- Detected existing workspace from [prior date]
- Assessment: [quality evaluation]
- Decision: [continue/archive/salvage]
- Reasoning: [why]

Common Rationalizations (RED FLAGS)

If you catch yourself thinking ANY of these, STOP:

All of these mean: Follow the process. It exists because these rationalizations lead to bad outcomes.

Extreme Pressure Handling

If user requests something genuinely impossible:

• "Complete 15-plugin analysis with full diagrams in 1 hour"

Provide scoped alternative:

"I can't do complete analysis of 15 plugins in 1 hour while maintaining quality. Here are realistic options:

A) Quick overview (1 hour): Holistic scan, plugin inventory, high-level architecture diagram, documented limitations

B) Focused deep-dive (1 hour): Pick 2-3 critical plugins, full analysis of those, others documented as "not analyzed"

C) Use existing docs (15 min): Synthesize existing README.md, CLAUDE.md with quick verification

D) Reschedule (recommended): Full systematic analysis takes 4-6 hours for this scale

Which approach fits your needs?"

DO NOT: Refuse the task entirely. Provide realistic scoped alternatives.

Documentation Contracts

See individual skill files for detailed contracts:

• 01-discovery-findings.md contract → analyzing-unknown-codebases skill
• 02-subsystem-catalog.md contract → analyzing-unknown-codebases skill
• 03-diagrams.md contract → generating-architecture-diagrams skill
• 04-final-report.md contract → documenting-system-architecture skill
• Validation protocol → validating-architecture-analysis skill

Workflow Summary

1. Create workspace (docs/arch-analysis-YYYY-MM-DD-HHMM/)
2. Write coordination plan (00-coordination.md)
3. Holistic assessment → 01-discovery-findings.md
4. Decide: Sequential or Parallel? (document reasoning)
5. Spawn subagents for analysis → 02-subsystem-catalog.md
6. VALIDATE subsystem catalog (mandatory gate)
7. Spawn diagram generation → 03-diagrams.md
8. VALIDATE diagrams (mandatory gate)
9. Synthesize final report → 04-final-report.md
10. VALIDATE final report (mandatory gate)
11. Provide cleanup recommendations for temp/

Every step is mandatory. No exceptions for time pressure, complexity, or stakeholder demands.

Success Criteria

You have succeeded when:

• Workspace structure exists with all numbered documents
• Coordination log documents all major decisions
• All outputs passed validation gates
• Subagent orchestration used appropriately for scale
• Limitations explicitly documented if time-constrained
• User receives navigable, validated architecture documentation

You have failed when:

• Files scattered outside workspace
• No coordination log showing decisions
• Validation skipped "to save time"
• Worked solo despite clear parallelization opportunity
• Produced rushed outputs without limitation documentation
• Rationalized shortcuts as "appropriate trade-offs"

Anti-Patterns

❌ Skip workspace creation "I'll just write files to project root"

❌ No coordination logging "I'll just do the work without documenting strategy"

❌ Work solo despite scale "Orchestration overhead isn't worth it"

❌ Skip validation "I already reviewed it myself"

❌ Bypass BLOCK status "The validation is too strict, I'll proceed anyway"

❌ Complete refusal under pressure "I can't do this properly in 3 hours, so I won't do it" (Should: Provide scoped alternative)

Converted and distributed by TomeVault — claim your Tome and manage your conversions.