菜单
Use when analyzing existing codebases to generate architecture documentation - coordinates subagent-driven exploration with mandatory workspace structure, validation gates, and pressure-resistant workflows
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Use when assessing codebase architecture and you feel pressure to soften critique, lead with strengths, or frame problems diplomatically - provides evidence-based critical assessment resisting relationship and economic pressures
Use when cataloging technical debt under time pressure and tempted to explain choices instead of delivering document - enforces execution discipline with scoped delivery patterns for partial catalogs
Use when stakeholders pressure you to change technical priorities and you're tempted to compromise on security-first or call it synthesis - enforces risk-based prioritization over stakeholder preferences
Use when you have architecture documentation from system-archaeologist and need critical assessment, refactoring recommendations, or improvement prioritization - routes to appropriate architect specialist skills
Master A2C, A3C, SAC, TD3 - actor-critic methods for continuous control
Master ε-greedy, UCB, curiosity-driven, RND, intrinsic motivation exploration
| 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 |
| mode | true |
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.
Before any analysis:
mkdir -p docs/arch-analysis-$(date +%Y-%m-%d-%H%M)/temp
Why this is mandatory:
Common rationalization: "This feels like overhead when I'm pressured"
Reality: 10 seconds to create workspace saves hours of file hunting and context loss.
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:
Common rationalization: "I'll just do the work, documentation is overhead"
Reality: Undocumented work is unreviewable and non-reproducible.
Before diving into details, perform systematic scan:
Write findings to 01-discovery-findings.md
Why holistic before detailed:
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.
Decision point: Sequential vs Parallel
Use SEQUENTIAL when:
Use PARALLEL when:
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.
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:
After EVERY major document is produced, validate before proceeding.
What "validation gate" means:
Two validation approaches:
A) Separate Validation Subagent (PREFERRED)
B) Systematic Self-Validation (ACCEPTABLE)
Validation checklist (either approach):
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:
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.
When validator returns NEEDS_REVISION with CRITICAL issues:
DO NOT:
From baseline testing: Agents WILL respect validation when it's clear and authoritative. Make validation clear and authoritative.
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.
Common scenario: "We started this analysis last week, finish it"
Checklist:
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]
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. |
| "Architecture analysis doesn't need exhaustive review" | True. But it DOES need systematic method. |
| "Meeting-ready outputs" justify shortcuts | Stakeholders deserve accurate info, not rushed guesses. |
All of these mean: Follow the process. It exists because these rationalizations lead to bad outcomes.
If user requests something genuinely impossible:
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.
See individual skill files for detailed contracts:
01-discovery-findings.md contract → analyzing-unknown-codebases skill02-subsystem-catalog.md contract → analyzing-unknown-codebases skill03-diagrams.md contract → generating-architecture-diagrams skill04-final-report.md contract → documenting-system-architecture skillvalidating-architecture-analysis skill1. 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.
You have succeeded when:
You have failed when:
❌ 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)