project-deep-auditor

name	project-deep-auditor
description	深度審視本地軟體專案的架構、程式碼健康度、依賴策略、運維就緒度、測試驗證、 生態系適配與目標對齊，並產出帶證據的研究報告與決策包。 使用時機：當使用者想要全面審視一個專案的架構、評估技術債、 盤點程式碼品質、比較業界最佳實踐、做目標對齊檢查、 或是在重大決策前需要深度研究報告時。 也適用於：「幫我看看這個 repo」「這個專案架構有什麼問題」 「我想重構但不確定從哪開始」「幫我做技術評估」「audit this project」 「review the architecture」「什麼該改什麼不該動」 「這個專案方向對嗎」「幫我看看整體 portfolio」。 支援多種專案類型：web app、agent system、robotics、Obsidian vault。 兩個指令模式：audit-plan（本地掃描＋產出研究計畫）、 audit-run（核可後執行完整研究與報告）。

Project Deep Auditor

以「帶證據的 judgment」為目標，不以「多給建議」為目標。

Core Rules

1. 沒有證據，不准下判斷。
2. 先鎖 scope，再做 web research。
3. 先掃本地，再決定外部搜尋方向。
4. Final recommendations 只能由 lead synthesizer 輸出。
5. Community signal 不可單獨支撐結論。
6. 分清 observation 與 inference。
7. 不確定就明講 unknown，不要補腦。

詳細規則：讀 references/evidence-rules.md

Modes

audit-plan

做本地掃描與研究規劃，不做最終 judgment。

流程：

1. 檢測可用工具（見下方 Tool Detection）
2. 建立 plans/{run_id}/scope.md（見下方 Scope Locking）
3. 7 軸並行掃描本地專案（Obsidian vault 使用替換軸，見 references/research-matrix.md）
4. 每軸用一個 subagent，role prompt 見 prompts/axis-scanner.md
5. Lead agent 合併各軸 open questions，產出 plans/{run_id}/current-audit-plan.md
6. 衍生 plans/{run_id}/web-research-agenda.md（status: draft）
7. 停在這裡，等使用者確認

輸出（{run_id} = YYYY-MM-DDTHH-MM-SS）：

• plans/{run_id}/scope.md
• plans/{run_id}/current-audit-plan.md
• plans/{run_id}/web-research-agenda.md
• scratchpads/{run_id}/axis-*.md

current-audit-plan.md 結構

# Audit Plan
# Generated: {timestamp}
# Run ID: {run_id}
# Target: {repo_name}

## Local Scan Summary
- Axes scanned: {list}
- Total findings: {count by impact level}
- Scan coverage: {which modules were touched}

## Per-Axis Status
| Axis | Findings | High Impact | Medium Impact | Low Impact | Open Questions |
|------|----------|-------------|---------------|------------|----------------|

## Consolidated Open Questions
- Q1: ... (from axis: ...)

## Preliminary Observations
(基於本地掃描的初步觀察——不使用 Keep/Fix/Explore)

## Recommended Next Steps
- [ ] Confirm web-research-agenda.md
- [ ] Proceed to audit-run
- [ ] Narrow scope / Expand scope

web-research-agenda.md Approval Gate

---
status: draft | approved
approved_by: (使用者名稱或 "owner")
approved_at: (ISO timestamp)
generated_from: (對應的 run_id)
---

• audit-plan 產出時 status 為 draft
• 使用者確認後改為 approved
• audit-run 啟動時檢查 status 必須為 approved

audit-run

在已有 plan 的前提下執行完整審計。

前提：plans/{run_id}/web-research-agenda.md 存在且 status: approved。

流程：

1. 驗證 approval status，若為 draft 則停止
2. 按主題分批執行網路研究，role prompt 見 prompts/web-researcher.md
3. 各研究結果寫入 scratchpads/{run_id}/web-*.md
4. Lead synthesizer 整合所有 scratchpads，role prompt 見 prompts/lead-synthesizer.md
5. 產出最終報告

輸出（延續同一個 {run_id}）：

• scratchpads/{run_id}/web-*.md
• scratchpads/{run_id}/research-report.md
• scratchpads/{run_id}/decision-packet.md

portfolio-review

在完成多個專案的 audit-run 之後，做跨專案的 meta-level 分析。

前提：

• 至少 2 個專案各自完成 audit-run
• 每個專案的 scope.md 都有 strategic_context
• 只完成 audit-plan 的專案可納入但標記 [PARTIAL-AUDIT]，判斷權重降級

路徑定位：預設讀取各專案的 scratchpads/latest/ 和 plans/latest/（symlink 指向最新 run）。如果使用者指定特定 run_id，改讀 scratchpads/{run_id}/ 和 plans/{run_id}/。

流程：

1. 讀取所有專案的 plans/latest/scope.md（strategic context）
2. 讀取所有專案的 scratchpads/latest/research-report.md（完整版優先；若只有 audit-plan 則讀 axis scratchpads）
3. 讀取所有專案的 scratchpads/latest/decision-packet.md（如果存在）
4. 產出 portfolio-level judgment

輸出：portfolio-review.md（在當前工作目錄，不在個別專案內）

Workflow

Stage 1: Local Parallel Scan

使用 Agent tool 同時派遣多個 subagent（subagent_type: general-purpose）。

每個 subagent 接收：

• 目標 repo 路徑
• 指定的軸名稱 + 掃描策略（從 references/research-matrix.md）
• 輸出格式（從 references/output-schema.md）
• Scope boundaries（從 plans/{run_id}/scope.md）
• Role prompt（從 prompts/axis-scanner.md）

每個 subagent 只產出：Findings, Evidence, Open Questions, Suggested External Queries, Deferred Threads。

寫入 scratchpads/{run_id}/axis-*.md。

Stage 2: Web Research Gated

先整合 Stage 1 的 open questions，再決定要查什麼。

產出 plans/{run_id}/web-research-agenda.md，分 4 類：

• Official docs（框架/語言官方文件）
• PR / Issues（GitHub 上的討論）
• Community signals（Reddit、X、HN、部落格）
• Reference repo comparison

使用者核可後才開始執行（status: draft → approved）。

Web researcher subagent 接收：

• 查詢主題（從 web-research-agenda.md）
• 輸出格式（從 references/output-schema.md）
• 證據規則（從 references/evidence-rules.md）
• Role prompt（從 prompts/web-researcher.md）

Stage 3: Single-Voice Synthesis

不派 subagent。主 agent 擔任 lead synthesizer。

讀取 prompts/lead-synthesizer.md 的 role prompt。

整合所有 scratchpads，做 evidence reconciliation：

• 交叉驗證不同來源的 findings
• 降級缺乏交叉驗證的 community signals
• 標記 [UNVERIFIED] 結論和 [URL-MISSING] 引用
• 驗證所有 file_path:line_number 引用

Recommendations 只允許三類：Keep / Fix / Explore。

使用模板：references/research-report-template.md + references/decision-packet-template.md

Tool Detection

啟動時自動檢測可用工具：

1. gh auth status → gh CLI 是否可用
2. 嘗試 WebSearch 一次簡單 query → WebSearch 是否可用
3. 將結果寫入 plans/{run_id}/scope.md 的 available_tools

Tool Fallback Chain

工具	Fallback	降級後果
WebSearch / WebFetch	無	該 research lane 標 [TOOL-UNAVAILABLE]
gh CLI	WebSearch site:github.com	標 [gh-fallback: WebSearch]，可信度降一級
Agent tool	串行模式	功能不變，速度變慢

Scope Locking

每次審計必須先建立 plans/{run_id}/scope.md：

## Target
- repo_path:
- repo_name:
- primary_language:
- framework:
- project_type: web-app | agent-system | robotics | obsidian-vault | mixed
- last_commit:

## Goal
- audit_goal:
- requested_depth: shallow | standard | exhaustive
- requested_comparisons:

## Strategic Context
- project_docs_path:
- stated_project_goal: (從專案文件提取)
- owner_stated_goal: (使用者口述或從外部引用)
- success_definition:
- why_now:
- relationship_to_other_projects:
- code_doc_consistency: pending | checked

## Available Tools
- agent_tool: true | false
- web_search: true | false
- gh_cli: true | false

## Boundaries
### In-Scope Modules
### Out-of-Scope Modules (含排除理由)

## Assumptions
## Constraints

硬規則：scope 不清就停在 audit-plan，不可進 audit-run。

Scratchpad Discipline

所有 scratchpads 存放在 run-specific timestamped directory：scratchpads/{YYYY-MM-DDTHH-MM-SS}/

• Evidence Log 採 append-only
• 每次審計建新 run directory，不覆寫舊的
• 審計完成後建 latest symlink 指向最新 run directory
• 歷史 run 自動保留，可做 diff 比較

Failure & Recovery

Subagent 產出格式不完整

標記為 [INCOMPLETE]，在報告中註明「此軸資料不完整」。不重跑，除非使用者要求。

Web research 搜不到有用結果

記錄 [NO-RESULTS] 和實際使用的 query。不捏造結果。在報告標註「外部證據不足」。

目標 repo 太大

採用 sampling 策略：優先掃描 scope 中 in-scope modules、入口檔、最近修改的檔案、依賴宣告。在 scratchpad 標註 sampled, not exhaustive。

audit-run 缺少已確認的 plan

拒絕執行，提示先跑 audit-plan。如果 agenda status: draft 也拒絕。

工具不可用

按 Tool Fallback Chain 降級。所有降級都在 scratchpad 中標註。

Loading Guide

按需讀檔，不要一次全部載入：

用途	讀取
流程與模式	本檔（SKILL.md）
研究軸定義	references/research-matrix.md（只讀你的軸）
輸出格式	references/output-schema.md
證據規則	references/evidence-rules.md
目標對齊 rubric	references/goal-alignment-rubric.md
最終報告模板	references/research-report-template.md
決策包模板	references/decision-packet-template.md
Axis scanner prompt	prompts/axis-scanner.md
Web researcher prompt	prompts/web-researcher.md
Lead synthesizer prompt	prompts/lead-synthesizer.md
報告 frontmatter	assets/report-header.md

Gotchas

• 不要把 reference repo 的做法直接當最佳實踐——那是別人的選擇。
• 不要讓 web research 反過來主導本地審計——本地掃描是基礎，web research 是補充。
• 不要讓 subagent 直接寫 roadmap——roadmap 只能由 lead synthesizer 在 decision-packet 中產出。
• 不要因為找到很多 GitHub issues 就假設問題重要——看 maintainer 身份、issue 時間、是否已解決。
• 不要省略 unknowns——unknown 本身就是審計結果，比硬擠出的結論更有價值。
• 不要在 audit-plan 階段使用 Keep/Fix/Explore——這些判斷只在 audit-run 的 synthesis 階段出現。
• 不要一次載入所有 reference files——按需讀取，節省 context window。
• Obsidian vault 不要用 code audit 的方法——改用替換軸（Knowledge Architecture, Information Flow, Maintenance Health, Retrieval Effectiveness）。