Back to Details

codebase-recon

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Codebase Analysis

代码库分析

Evidence-based investigation → findings → confidence-tracked conclusions.
基于证据的调查 → 发现 → 跟踪置信度的结论。

Steps

步骤

  1. Gather evidence from multiple sources (code, docs, tests, history)
  2. Track confidence level as investigation progresses
  3. Based on findings:
    • If pattern analysis needed → load the 
      outfitter:patterns
      skill
    • If root cause investigation → load the 
      outfitter:find-root-causes
      skill
    • If ready to report → load the 
      outfitter:report-findings
      skill
  4. Deliver findings with confidence level and caveats
<when_to_use>
  • Codebase exploration and understanding
  • Architecture analysis and mapping
  • Pattern extraction and recognition
  • Technical research within code
  • Performance or security analysis
NOT for: wild guessing, assumptions without evidence, conclusions before investigation
</when_to_use>
<confidence>
BarLvlNameAction
░░░░░
0GatheringCollect initial evidence
▓░░░░
1SurveyingBroad scan, surface patterns
▓▓░░░
2InvestigatingDeep dive, verify patterns
▓▓▓░░
3AnalyzingCross-reference, fill gaps
▓▓▓▓░
4SynthesizingConnect findings, high confidence
▓▓▓▓▓
5ConcludedDeliver findings
Calibration: 0=0–19%, 1=20–39%, 2=40–59%, 3=60–74%, 4=75–89%, 5=90–100%
Start honest. Clear codebase + focused question → level 2–3. Vague or complex → level 0–1.
At level 4: "High confidence in findings. One more angle would reach full certainty. Continue or deliver now?"
Below level 5: include 
△ Caveats
section.
</confidence> <principles>
  1. 从多个来源收集证据（代码、文档、测试、历史记录）
  2. 随着调查推进跟踪置信度等级
  3. 根据发现：
    • 如果需要模式分析 → 加载
      outfitter:patterns
      技能
    • 如果需要根因调查 → 加载
      outfitter:find-root-causes
      技能
    • 如果准备好报告 → 加载
      outfitter:report-findings
      技能
  4. 交付带有置信度等级和注意事项的发现结果
<when_to_use>
  • 代码库探索与理解
  • 架构分析与映射
  • 模式提取与识别
  • 代码内的技术研究
  • 性能或安全分析
不适用场景：凭空猜测、无证据假设、未调查就下结论
</when_to_use>
<confidence>
进度条等级名称操作
░░░░░
0收集阶段收集初始证据
▓░░░░
1概览阶段广泛扫描，识别表面模式
▓▓░░░
2调查阶段深入研究，验证模式
▓▓▓░░
3分析阶段交叉引用，填补空白
▓▓▓▓░
4综合阶段关联发现，高置信度
▓▓▓▓▓
5完成阶段交付发现结果
校准标准：0=0–19%，1=20–39%，2=40–59%，3=60–74%，4=75–89%，5=90–100%
从实际情况出发。代码库清晰且问题明确 → 等级2–3。问题模糊或场景复杂 → 等级0–1。
等级4时："对发现结果有高置信度。再从一个角度验证即可达到完全确定。是否继续调查或现在交付？"
等级低于5时：需包含
△ 注意事项
部分。
</confidence> <principles>

Core Methodology

核心方法论

Evidence over assumption — investigate when you can, guess only when you must.
Multi-source gathering — code, docs, tests, history, web research, runtime behavior.
Multiple angles — examine from different perspectives before concluding.
Document gaps — flag uncertainty with △, track what's unknown.
Show your work — findings include supporting evidence, not just conclusions.
Calibrate confidence — distinguish fact from inference from assumption.
</principles>
<evidence_gathering>
证据优先，假设为辅 —— 尽可能调查，仅在必要时猜测。
多源收集 —— 代码、文档、测试、历史记录、网络研究、运行时行为。
多角度分析 —— 下结论前从不同视角审视。
记录空白 —— 用△标记不确定性，跟踪未知内容。
展示调查过程 —— 发现结果需包含支持证据，而非仅结论。
校准置信度 —— 区分事实、推论与假设。
</principles>
<evidence_gathering>

Source Priority

来源优先级

  1. Direct observation — read code, run searches, examine files
  2. Documentation — official docs, inline comments, ADRs
  3. Tests — reveal intended behavior and edge cases
  4. History — git log, commit messages, PR discussions
  5. External research — library docs, Stack Overflow, RFCs
  6. Inference — logical deduction from available evidence
  7. Assumption — clearly flagged when other sources unavailable
  1. 直接观察 —— 阅读代码、运行搜索、检查文件
  2. 文档 —— 官方文档、内联注释、架构决策记录（ADRs）
  3. 测试 —— 揭示预期行为和边缘情况
  4. 历史记录 —— Git日志、提交信息、PR讨论
  5. 外部研究 —— 库文档、Stack Overflow、RFC文档
  6. 推论 —— 从现有证据进行逻辑推导
  7. 假设 —— 当其他来源不可用时需明确标记

Investigation Patterns

调查模式

Start broad, then narrow:
  • File tree → identify relevant areas
  • Search patterns → locate specific code
  • Code structure → understand without full content
  • Read targeted files → examine implementation
  • Cross-reference → verify understanding
Layer evidence:
  • What does the code do? (direct observation)
  • Why was it written this way? (history, comments)
  • How does it fit the system? (architecture, dependencies)
  • What are the edge cases? (tests, error handling)
Follow the trail:
  • Function calls → trace execution paths
  • Imports/exports → map dependencies
  • Test files → understand usage patterns
  • Error messages → reveal assumptions
  • Comments → capture historical context
</evidence_gathering>
<output_format>
先广后窄：
  • 文件树 → 识别相关区域
  • 搜索模式 → 定位特定代码
  • 代码结构 → 无需通读全部内容即可理解
  • 阅读目标文件 → 检查实现细节
  • 交叉引用 → 验证理解
分层证据：
  • 代码的功能是什么？（直接观察）
  • 为什么要这样编写？（历史记录、注释）
  • 它如何融入系统？（架构、依赖关系）
  • 边缘情况有哪些？（测试、错误处理）
追踪线索：
  • 函数调用 → 跟踪执行路径
  • 导入/导出 → 映射依赖关系
  • 测试文件 → 理解使用模式
  • 错误信息 → 揭示隐含假设
  • 注释 → 捕捉历史背景
</evidence_gathering>
<output_format>

During Investigation

调查过程中

After each evidence-gathering step emit:
  • Confidence: {BAR} {NAME}
  • Found: { key discoveries }
  • Patterns: { emerging themes }
  • Gaps: { what's still unclear }
  • Next: { investigation direction }
完成每个证据收集步骤后输出：
  • 置信度： {进度条} {阶段名称}
  • 发现： {关键成果}
  • 模式： {浮现的主题}
  • 空白： {仍不明确的内容}
  • 下一步： {调查方向}

At Delivery (Level 5)

交付阶段（等级5）

Findings

发现结果

{ numbered list of discoveries with supporting evidence }
  1. {FINDING} — evidence: {SOURCE}
  2. {FINDING} — evidence: {SOURCE}
{带支持证据的编号发现列表}
  1. {发现内容} —— 证据：{来源}
  2. {发现内容} —— 证据：{来源}

Patterns

模式

{ recurring themes or structures identified }
{识别出的重复主题或结构}

Implications

影响

{ what findings mean for the question at hand }
{发现结果与当前问题的关联}

Confidence Assessment

置信度评估

Overall: {BAR} {PERCENTAGE}%
High confidence areas:
  • {AREA} — {REASON}
Lower confidence areas:
  • {AREA} — {REASON}
总体：{进度条} {百分比}%
高置信度区域：
  • {区域} —— {原因}
低置信度区域：
  • {区域} —— {原因}

Supporting Evidence

支持证据

  • Code: { file paths and line ranges }
  • Docs: { references }
  • Tests: { relevant test files }
  • History: { commit SHAs if relevant }
  • External: { URLs if applicable }
  • 代码：{文件路径和行号范围}
  • 文档：{引用来源}
  • 测试：{相关测试文件}
  • 历史记录：{相关提交SHA（若有）}
  • 外部资源：{URL（若适用）}

Below Level 5

等级低于5时

△ Caveats

△ 注意事项

Assumptions:
  • {ASSUMPTION} — { why necessary, impact if wrong }
Gaps:
  • {GAP} — { what's missing, how to fill }
Unknowns:
  • {UNKNOWN} — { noted for future investigation }
</output_format>
<specialized_techniques>
Load skills for specialized analysis (see Steps section):
  • Pattern analysis → 
    outfitter:patterns
  • Root cause investigation → 
    outfitter:find-root-causes
  • Research synthesis → 
    outfitter:report-findings
  • Architecture analysis → see architecture-analysis.md
</specialized_techniques>
<workflow>
Loop: Gather → Analyze → Update Confidence → Next step
  1. Calibrate starting confidence — what do we already know?
  2. Identify evidence sources — where can we look?
  3. Gather systematically — collect from multiple angles
  4. Cross-reference findings — verify patterns hold
  5. Flag uncertainties — mark gaps with △
  6. Synthesize conclusions — connect evidence to insights
  7. Deliver with confidence level — clear about certainty
At each step:
  • Document what you found (evidence)
  • Note what it means (interpretation)
  • Track what's still unclear (gaps)
  • Update confidence bar
</workflow> <validation>
Before concluding (level 4+):
Check evidence quality:
  • ✓ Multiple sources confirm pattern?
  • ✓ Direct observation vs inference clearly marked?
  • ✓ Assumptions explicitly flagged?
  • ✓ Counter-examples considered?
Check completeness:
  • ✓ Original question fully addressed?
  • ✓ Edge cases explored?
  • ✓ Alternative explanations ruled out?
  • ✓ Known unknowns documented?
Check deliverable:
  • ✓ Findings supported by evidence?
  • ✓ Confidence calibrated honestly?
  • ✓ Caveats section included if <100%?
  • ✓ Next steps clear if incomplete?
</validation> <rules>
ALWAYS:
  • Investigate before concluding
  • Cite evidence sources with file paths/URLs
  • Use confidence bars to track certainty
  • Flag assumptions and gaps with △
  • Cross-reference from multiple angles
  • Document investigation trail
  • Distinguish fact from inference
  • Include caveats below level 5
NEVER:
  • Guess when you can investigate
  • State assumptions as facts
  • Conclude from single source
  • Hide uncertainty or gaps
  • Skip validation checks
  • Deliver without confidence assessment
  • Conflate evidence with interpretation
</rules> <references>
Core methodology:
  • confidence.md — confidence calibration (shared with pathfinding)
Micro-skills (load as needed):
  • outfitter:patterns
    — extracting and validating patterns
  • outfitter:find-root-causes
    — systematic problem diagnosis
  • outfitter:report-findings
    — multi-source research synthesis
Local references:
  • architecture-analysis.md — system structure mapping
Related skills:
  • outfitter:pathfinding
    — clarifying requirements before analysis
  • outfitter:debugging
    — structured bug investigation
</references>
假设：
  • {假设内容} —— {必要性，若错误的影响}
空白：
  • {空白内容} —— {缺失的信息，填补方式}
未知：
  • {未知内容} —— {记录以供未来调查}
</output_format>
<specialized_techniques>
加载用于专项分析的技能（见步骤部分）：
  • 模式分析 → 
    outfitter:patterns
  • 根因调查 → 
    outfitter:find-root-causes
  • 研究综合 → 
    outfitter:report-findings
  • 架构分析 → 参见architecture-analysis.md
</specialized_techniques>
<workflow>
循环：收集 → 分析 → 更新置信度 → 下一步
  1. 校准初始置信度 —— 我们已知晓哪些内容？
  2. 确定证据来源 —— 可以从哪些渠道获取信息？
  3. 系统化收集 —— 从多角度收集证据
  4. 交叉验证发现 —— 验证模式是否成立
  5. 标记不确定性 —— 用△标记空白
  6. 综合结论 —— 将证据与见解关联
  7. 按置信度等级交付 —— 明确确定性
每个步骤需：
  • 记录发现的内容（证据）
  • 说明其含义（解读）
  • 跟踪仍不明确的内容（空白）
  • 更新进度条
</workflow> <validation>
结论前（等级4及以上）：
检查证据质量：
  • ✓ 是否有多个来源确认模式？
  • ✓ 是否明确区分直接观察与推论？
  • ✓ 是否明确标记假设？
  • ✓ 是否考虑反例？
检查完整性：
  • ✓ 是否完全解决原始问题？
  • ✓ 是否探索边缘情况？
  • ✓ 是否排除其他解释？
  • ✓ 是否记录已知的未知内容？
检查交付物：
  • ✓ 发现结果是否有证据支持？
  • ✓ 置信度是否如实校准？
  • ✓ 置信度低于100%时是否包含注意事项部分？
  • ✓ 若未完成，下一步是否明确？
</validation> <rules>
必须遵守：
  • 下结论前先调查
  • 引用证据来源时需包含文件路径/URL
  • 使用进度条跟踪确定性
  • 用△标记假设和空白
  • 从多角度交叉引用
  • 记录调查轨迹
  • 区分事实与推论
  • 等级低于5时包含注意事项
严禁：
  • 可调查时却猜测
  • 将假设陈述为事实
  • 仅从单一来源下结论
  • 隐瞒不确定性或空白
  • 跳过验证检查
  • 未做置信度评估就交付
  • 将证据与解读混为一谈
</rules> <references>
核心方法论：
  • confidence.md —— 置信度校准（与路径规划技能共享）
微技能（按需加载）：
  • outfitter:patterns
    —— 提取与验证模式
  • outfitter:find-root-causes
    —— 系统化问题诊断
  • outfitter:report-findings
    —— 多源研究综合
本地参考：
  • architecture-analysis.md —— 系统结构映射
相关技能：
  • outfitter:pathfinding
    —— 分析前明确需求
  • outfitter:debugging
    —— 结构化bug调查
</references>