| name | using-system-archaeologist |
| description | Use when analyzing existing codebases to generate architecture documentation - coordinates subagent-driven exploration with mandatory workspace structure, validation gates, and pressure-resistant workflows |
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.
Context Conservation (CRITICAL)
You are a COORDINATOR, not an analyst. Your primary context is precious - preserve it for orchestration decisions, not detailed code reading.
The Delegation Imperative
| Task Type | Your Role | Subagent Role |
|---|
| Subsystem analysis | Spawn codebase-explorer | Read files, produce catalog entries |
| Validation | Spawn analysis-validator | Check contracts, produce reports |
| Diagram generation | Spawn diagram subagent | Generate Mermaid/PlantUML |
| Quality assessment | Spawn quality subagent | Analyze patterns, produce assessment |
| Security surface | Spawn security subagent | Map boundaries, flag concerns |
What You DO (Coordinator):
- Create workspace and coordination plan
- Make orchestration decisions (parallel vs sequential)
- Spawn subagents with clear task specifications
- Read subagent outputs (summaries, not raw files)
- Make proceed/revise decisions based on validation
- Synthesize final deliverables from subagent work
What You DO NOT Do (Delegate Instead):
- Read implementation files directly (subagent reads, you get summary)
- Perform detailed pattern analysis (spawn specialist)
- Write catalog entries yourself (spawn codebase-explorer)
- Validate your own work (spawn analysis-validator)
- Generate diagrams from scratch (spawn diagram agent)
Rationalization Blockers
| Thought | Reality |
|---|
| "I'll just quickly read this file" | Spawn subagent. Your context is for coordination. |
| "It's faster if I do it myself" | Subagents preserve your context for later decisions. |
| "Only a few files to check" | "Few" files become many. Delegate from the start. |
| "I need to understand the code" | You need to understand the STRUCTURE. Subagents report findings. |
| "Spawning overhead isn't worth it" | Context exhaustion is worse. Always delegate detailed work. |
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"
How to Access Reference Sheets
IMPORTANT: All reference sheets are located in the SAME DIRECTORY as this SKILL.md file.
When this skill is loaded from:
skills/using-system-archaeologist/SKILL.md
Reference sheets like analyzing-unknown-codebases.md are at:
skills/using-system-archaeologist/analyzing-unknown-codebases.md
NOT at:
skills/analyzing-unknown-codebases.md ← WRONG PATH
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 1.5: Offer Deliverable Menu (MANDATORY)
After workspace creation, present deliverable options using AskUserQuestion tool.
See deliverable-options.md for the complete menu (Options A-G).
Key options:
- A) Full Analysis - Comprehensive documentation
- B) Quick Overview - Fast turnaround, documented limitations
- C) Architect-Ready - Full analysis + improvement planning
- E) Full + Security - Security surface mapping included
- F) Full + Quality - Test infrastructure + dependency analysis
- G) Comprehensive - Everything
Common rationalization: "User didn't specify, so I'll default to full analysis"
Reality: Always offer choice explicitly. Different needs require different outputs.
Step 2: Write Coordination Plan
After documenting deliverable choice, 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]
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:
- Directory structure - Map organization (feature? layer? domain?)
- Entry points - Find main files, API definitions, config
- Technology stack - Languages, frameworks, dependencies
- Subsystem identification - Identify 4-12 major cohesive groups
Write findings to 01-discovery-findings.md
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 vs Ultralarge per-module track
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–100K LOC, 10+ plugins/services)
- Subsystems are loosely coupled
Use ULTRALARGE PER-MODULE TRACK when ANY of:
- Source LOC > 100,000
- Subsystem candidates > 12
- Test corpus LOC ≥ source LOC
- Doc corpus > 500 markdown files
- Plugin-registry architecture with extensible categories
The ultralarge track abandons single-pass orchestration and switches to manual subsystem partitioning + per-module review-with-scribe. Use the /analyze-ultralarge command, not /analyze-codebase. See:
Common rationalization: "Solo work is faster than coordination overhead"
Reality: For large systems, orchestration overhead (5 min) saves hours of sequential work. For ultralarge systems, single-pass orchestration produces a thin, sample-driven catalog that misses entire subsystems — the per-module track is non-negotiable at that scale.
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)
Step 6: Validation Gates (MANDATORY)
After EVERY major document is produced, validate before proceeding.
SPAWN VALIDATION SUBAGENT (Required for ≥3 subsystems)
- Spawn dedicated validation subagent using Task tool
- Agent reads document + contract, produces validation report
- Write validation report to
temp/validation-[document].md
Self-validation ONLY permitted when ALL conditions met:
- Single-subsystem analysis (1-2 subsystems only)
- Total analysis time < 30 minutes
- YOU personally did ALL the work (no subagents involved)
- AND you document validation EVIDENCE (not just checkmarks)
If ANY condition is not met → SPAWN VALIDATION SUBAGENT. No exceptions.
Validation Rationalization Blockers
| Excuse | Reality |
|---|
| "We have 45 minutes, no time for validation" | Validation takes 5-10 minutes. Spawn validator. |
| "I already reviewed it while writing" | Self-review ≠ validation. Spawn validator. |
| "I'll do systematic self-validation" | Multiple subsystems require independent validator. Spawn validator. |
| "Most work is already done" | Prior work must be validated. Spawn validator. |
| "Time pressure - I'll document limitations instead" | Documented limitations don't excuse skipping validation. Spawn validator. |
| "It's a simple codebase" | Simple ≠ correct. Spawn validator. |
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.
Step 7: Handle Validation Failures
When validator returns NEEDS_REVISION with CRITICAL issues:
- Read validation report (temp/validation-*.md)
- Identify specific issues (not general "improve quality")
- Spawn original subagent again with fix instructions
- Re-validate after fix
- Maximum 2 retries - if still failing, escalate to user
DO NOT:
- Proceed to next phase despite BLOCK status
- Make fixes yourself without re-spawning subagent
- Rationalize "it's good enough"
- Question validator authority
Working Under Pressure
Time Constraints Are Not Excuses to Skip Process
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
- 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.
Resuming Prior Work (Sunk-Cost Discipline)
Common scenario: "We started this analysis last week, finish it."
Prior work is a hypothesis, not a foundation. Validate before continuing.
Checklist:
- Find existing workspace - Look in
docs/arch-analysis-*/.
- Read the coordination log (
00-coordination.md) - Understand what was done, what remains, and why work stopped.
- Assess quality - Is the prior catalog/diagram/report contract-compliant? Are confidence levels documented? Were validation gates passed?
- Make an EXPLICIT continue/archive/salvage decision:
- Continue - Prior work passes contract + validation. Resume from the last checkpoint. Update coordination log.
- Archive - Prior work is structurally flawed (wrong scope, wrong contract, no validation). Archive the old workspace (
mv docs/arch-analysis-OLD docs/arch-analysis-OLD.archived-$(date +%Y-%m-%d)), start fresh, document why.
- Salvage - Mixed quality. Keep good artifacts (e.g., discovery findings), redo bad ones (e.g., un-validated catalog). Document salvage decisions in the new coordination log.
- For incremental analysis on a moving codebase (prior analysis was complete but the code has since changed), use the delta-analysis path - see incremental-analysis.md.
DO NOT assume prior work is correct just because it exists. DO NOT silently continue without recording a decision.
Coordination log entry:
## Resume Decision - [timestamp]
- Detected existing workspace: docs/arch-analysis-2026-05-15-1430/
- Last completed step: 02-subsystem-catalog.md (validated APPROVED)
- Assessment: Catalog contract-compliant, 11/14 subsystems analyzed
- Decision: SALVAGE - keep catalog, redo diagrams (3 missing subsystems), continue from Step 7
- Reasoning: Validator approved catalog; diagrams were skipped at original session end
Extreme Pressure Handling
If user requests something genuinely impossible (e.g., "Complete 15-plugin analysis in 1 hour"):
Provide scoped alternatives:
A) Quick overview (1 hour): Holistic scan, plugin inventory, high-level diagram
B) Focused deep-dive (1 hour): Pick 2-3 critical plugins, full analysis of those
C) Use existing docs (15 min): Synthesize existing README.md, CLAUDE.md
D) Reschedule (recommended): Full analysis takes 4-6 hours for this scale
DO NOT refuse entirely. Provide realistic scoped alternatives.
Common Rationalizations (RED FLAGS)
If you catch yourself thinking ANY of these, STOP:
| Excuse | Reality |
|---|
| "Time pressure makes trade-offs appropriate" | Process prevents rework. Skipping process costs MORE time. |
| "This feels like overhead" | 5 minutes of structure saves hours of chaos. |
| "Working solo is faster" | Solo works for small tasks. Orchestration scales for large systems. |
| "I'll just write outputs directly" | Uncoordinated work creates inconsistent artifacts. |
| "Validation slows me down" | Validation catches errors before they cascade. |
| "I already checked it" | Self-review misses what fresh eyes catch. |
| "I can't do this properly in [short time]" | You can do SCOPED analysis properly. Document limitations. |
| "Rather than duplicate, I'll synthesize" | Existing docs ≠ systematic analysis. Do the work. |
| "Meeting-ready outputs" justify shortcuts | Stakeholders deserve accurate info, not rushed guesses. |
Specialist Subagent Integration
For complex codebases, leverage specialist subagents from other skillpacks.
See specialist-integration.md for:
- When to invoke specialists (by codebase type)
- Spawning pattern and output integration
- Cross-pack handoff points
- Technical accuracy escalation
Workflow Summary
1. Create workspace (docs/arch-analysis-YYYY-MM-DD-HHMM/)
1.5. Offer deliverable menu (A/B/C/D/E/F/G) - user chooses scope
2. Write coordination plan (00-coordination.md) with deliverable choice
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)
6.5. (Optional) Code quality assessment → 05-quality-assessment.md
6.6. (Optional) Security surface mapping → 07-security-surface.md
6.7. (Optional) Test infrastructure analysis → 09-test-infrastructure.md
6.8. (Optional) Dependency analysis → 10-dependency-analysis.md
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. (Optional) Generate architect handover → 06-architect-handover.md
12. Provide cleanup recommendations for temp/
Every step is mandatory except optional steps (6.5-6.8, 11). No exceptions.
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
You have failed when:
- Files scattered outside workspace
- No coordination log showing decisions
- Validation skipped "to save time"
- Self-validated multi-subsystem work instead of spawning validator
- Worked solo despite clear parallelization opportunity
- Produced rushed outputs without limitation documentation
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 subagent
"I already reviewed it myself" / "I'll do systematic self-validation"
❌ Self-validate multi-subsystem work
"Time constraints mean self-validation is acceptable" (NO - spawn validator)
❌ 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)
Documentation Contracts
See individual skill files for detailed contracts:
