teamai-cli 0.25.0 → 0.26.0-beta.1

package/skill-data/wiki/references/methodology/phase4-quality.md

@@ -0,0 +1,232 @@
+# Phase 4: Quality Assessment and Iterative Improvement
+
+> Helper tool: `python3 "{SKILL_DIR}/scripts/validate_kb.py" <output_dir>` automatically checks link integrity, anchor coverage, AI Quick Reference table coverage, bidirectional links, and README index inclusion rate
+
+## Five-Dimension Assessment Model
+
+| Dimension | Weight | Passing standard |
+|------|------|---------|
+| **Coverage** | 25% | ≥ 90% of core components are documented |
+| **Depth** | 25% | ≥ 80% of code entries can be located directly |
+| **Consistency** | 20% | 0 dead links, 0 contradictory descriptions |
+| **AI usability** | 20% | RAG retrieval accuracy ≥ 85% |
+| **Freshness** | 10% | Core document update lag ≤ 30 days |
+
+## Coverage Check
+
+```
+□ Does every code repository have a corresponding component design document?
+□ Does every core API have a product-to-code mapping?
+□ Does every data table have a schema description in some document?
+□ Is every MQ Exchange/Topic/Queue marked in the topology diagram?
+□ Is every error code in the mapping table?
+□ Is every config item in the configuration description?
+□ Is every scheduled task described in some document?
+```
+
+## RAG Retrieval Test Cases
+
+| Test type | Example question | Expected hit |
+|---------|---------|---------|
+| Component location | "Where is the code entry of {component}?" | Component design document |
+| Flow tracing | "What is the internal call chain of {API name}?" | Product-to-code mapping |
+| Constraint query | "What is the batch cap of {operation}?" | Rules cheat sheet |
+| State query | "Which operations can be executed in state {state}?" | State mutual exclusion rules |
+| Error investigation | "How do I investigate {error code}?" | Anti-patterns / troubleshooting records |
+| Code generation | "Write a Handler for {feature}" | SOP + interface contracts |
+| Concept disambiguation | "What is the difference between {A} and {B}?" | Product knowledge library |
+
+## Incremental Update Trigger Table
+
+| Trigger condition | Update action |
+|---------|---------|
+| New code repository | Generate a Type-4 component document |
+| API interface change | Update the Type-5 mapping + Type-6 cheat sheet |
+| New product feature | Update the Type-2 business architecture + Type-8a knowledge library |
+| Production incident | Add a Type-8d troubleshooting record + update Type-8b anti-patterns |
+| Architecture refactoring | Update the Type-1 architecture overview + affected Type-4 documents |
+| Config change | Update the configuration section of the corresponding component document |
+
+## Version Management Convention
+
+Maintain a change log at the bottom of every document:
+
+```markdown
+## 📝 Document Change Log
+
+### vX.Y (YYYY-MM-DD)
+- ✅ **Added**: {description of added content}
+- ✅ **Fixed**: {description of fixed content}
+- ✅ **Updated**: {description of updated content}
+- ⚠️ **Deprecated**: {description of deprecated content}
+```
+
+## Fixing Common Quality Issues
+
+| Issue | Fix method |
+|------|---------|
+| Dead links | Grep `](` links globally, or run `python3 "{SKILL_DIR}/scripts/validate_kb.py" <output_dir>` |
+| Inconsistent terminology | Build a glossary and replace globally |
+| Outdated code entries | Diff against the code repositories periodically |
+| Outdated constraint values | Cross-check against the product docs periodically |
+| AI retrieval failures | Add search-anchor keywords |
+| Isolated documents | Add bidirectional links |
+
+---
+
+## Complete Generation Pipeline Checklist
+
+### Phase 0 Checklist: Source Material Collection
+
+```
+□ All core code repositories cloned
+□ Product API docs collected (interface name / inputs / outputs / error codes)
+□ Product usage docs collected (usage limits / FAQ / billing description)
+□ Database schema extracted (DDL / table schemas)
+□ Workflow orchestration configs extracted (workflow_config etc.)
+□ Proto/IDL files extracted
+□ Error code definitions extracted
+```
+
+### Phase 1 Checklist: Architecture Reverse-Engineering
+
+```
+□ Code knowledge graph built (nodes + edges)
+□ Architecture layers determined (≥4 layers)
+□ Component relationship matrix built (N×N)
+□ Core call chains traced (≥5 core APIs)
+□ MQ topology inferred (Exchange/Topic/Queue/Routing Key)
+□ Database ER model built
+□ Glossary compiled (external-to-internal mappings)
+```
+
+### Phase 2 Checklist: Document Generation
+
+```
+□ [Type-1] Technical architecture overview document (1)
+  □ Includes the reader navigation guide
+  □ Includes AI retrieval routing rules
+  □ Includes core call chain sequence diagrams (≥5)
+  □ Includes the component relationship matrix
+  □ Includes the AI-only chapter 9
+  □ Includes the glossary
+
+□ [Type-2] Business architecture document (1)
+  □ Includes the product capability matrix
+  □ Includes the billing model (if applicable)
+  □ Includes the core entity lifecycle state machine
+
+□ [Type-3] Deployment architecture document (1)
+  □ Includes the service deployment matrix
+  □ Includes environment configuration
+
+□ [Type-4] Component design documents (N)
+  □ Each includes an AI Quick Reference table
+  □ Each includes bidirectional links
+  □ Each includes code entries (precise to the function)
+  □ Each includes an architecture diagram (ASCII Art)
+  □ Each includes core flow descriptions
+
+□ [Type-5] Product-to-code mapping document
+  □ Covers all core APIs
+  □ Each API includes a constraint table
+  □ Each API includes a call chain
+  □ Each API includes an error code mapping
+
+□ [Type-6] Product rules cheat sheet
+  □ Covers all rule categories
+  □ Constraint values are exact
+  □ Includes the state mutual exclusion matrix
+
+□ [Type-7] Business development SOP
+  □ Includes runnable code templates
+  □ Includes the error code mapping table
+  □ Includes the AI review checklist
+
+□ [Type-8] Knowledge enhancement documents
+  □ [8a] Product knowledge library (concept disambiguation)
+  □ [8b] Anti-patterns and pitfalls guide
+  □ [8c] RPC interface contracts
+  □ [8d] Troubleshooting case records
+```
+
+### Phase 3 Checklist: AI-Native Enhancement
+
+```
+□ All component documents include an AI Quick Reference table
+□ The Technical Architecture document includes retrieval routing rules
+□ All documents include a search-anchor
+□ Bidirectional link network complete (0 dead links)
+□ QA pairs generated (10~20)
+□ Document priorities defined
+```
+
+### Phase 3b Checklist: Graph Document Set (Graph RAG)
+
+```
+□ [G1] Component Dependency Matrix
+  □ N×N communication matrix complete
+  □ Forward/reverse dependency index
+  □ External service dependencies
+
+□ [G2] Component Call Chain Overview + state machine
+  □ End-to-end core API chains (read + write)
+  □ Complete mermaid state machine diagram
+  □ Core state field value transition path table (if internal state codes exist)
+  □ User-visible state ↔ internal state mapping (if multi-layer states exist)
+  □ Operation-state constraint quick lookup matrix (✅/❌)
+  □ AI state reasoning rules
+
+□ [G3] Data Flow and Storage Dependencies
+  □ Storage system dependency matrix
+  □ MQ queue topology
+  □ Cache strategy matrix
+
+□ [G4] Error Code Component Map
+  □ Error code range allocation table
+  □ External → internal error code mapping
+
+□ [G5] Cross-Component Interaction Scenarios
+  □ mermaid sequence diagrams for ≥10 scenarios
+  □ Every scenario has exception handling
+
+□ [G6] Knowledge Graph Triples
+  □ Ontology definition (entity types + relationship types)
+  □ ≥100 explicit triples
+  □ Multi-hop dependency path index
+  □ Reverse reachability index
+
+□ [G7] Architecture Risks and Impact Analysis
+  □ Component risk level summary table
+  □ Blast radius analysis (≥3 key components)
+  □ Cluster analysis
+  □ Change risk assessment matrix
+
+□ [G8] Core Config Parameter Index
+  □ Layered config architecture diagram (mermaid)
+  □ Config parameter table per layer (config item / default / behavior impact / change risk / activation)
+  □ Config change impact surface quick lookup matrix
+
+□ [G9] Business Rule Constraint Matrix
+  □ Operation precondition matrix
+  □ Detailed hardware constraint table
+  □ Migration constraint decision tree (mermaid)
+  □ Detailed billing constraint table
+  □ Special instance type constraint summary (✅/❌/⚠️)
+  □ AI reasoning rules quick lookup (mermaid flowchart)
+
+□ Graph directory README.md index complete
+  □ Lookup-by-question-type table
+  □ Retrieval routing rule suggestions
+```
+
+### Phase 4 Checklist: Quality Assessment
+
+```
+□ Coverage ≥ 90%
+□ Code entry precision ≥ 80%
+□ Dead links = 0 (confirm by running validate_kb.py)
+□ RAG retrieval accuracy ≥ 85%
+□ Core document update lag ≤ 30 days
+□ Terminology consistency check passed
+```

package/skill-data/wiki/references/overview.md

@@ -0,0 +1,124 @@
+# wiki: AI cognition engineering for large codebases
+
+> TeamAI built-in skill. The methodology, scripts and agent specifications are **not** copied into `.claude/`, `.codebuddy/`, `.cursor/` or any other agent directory: they ship inside the installed CLI and are served on demand by `teamai skill get wiki` (`--full` for the references too). What an agent reads therefore always matches the CLI it is running. `teamai skill path wiki` prints the directory that holds the scripts and templates, for the commands below that run them. TeamAI ships no separate team-wiki CLI, and no extra plugin is required.
+
+## Why this skill exists
+
+The AI comprehension problem of large projects:
+
+| Pain point | Symptom |
+|------|---------|
+| **Context does not fit** | 10+ repositories and hundreds of thousands of lines of code, far beyond the AI context window |
+| **Relations are unclear** | RPC/MQ/DB dependencies between microservices are scattered across repositories with no global view |
+| **Rules are not remembered** | Business constraints, state machines and config parameters hide deep in call chains |
+| **Answers are inaccurate** | AI sees only local code, lacks global architecture awareness, and hallucinates easily |
+| **High token consumption** | Every question re-reads large amounts of source, which is very inefficient |
+
+## How it is solved
+
+Architecture reverse-engineering **compresses the huge codebase into a structured knowledge base**:
+
+- Every conclusion has a code `file:line` as evidence
+- Every component relation carries a confidence label (`EXTRACTED` / `INFERRED` / `AMBIGUOUS`)
+- Every generation run produces accuracy statistics, with automatic warnings when thresholds are exceeded
+- AI reads the knowledge base instead of the source and gains global architecture awareness for **about 1/50 of the tokens**
+- In Phase 0, `teamai codebase --extract` can generate evidence-backed structural edges (TS/JS/Python/Go AST + multi-language heuristics)
+- After extraction, `teamai codebase --deep-enrich --project <slug> --output <repo>` can generate deterministic graph documents (G1/G2/G3) and deep knowledge; no separate team-wiki CLI is needed
+
+---
+
+## Deliverables
+
+```
+<output_dir>/
+├── README.md                           ← Retrieval routing guide (for AI)
+├── {project_name} Technical Architecture.md            ← Whole-system view, ~200KB
+├── {project_name} Business Architecture.md             ← Product capabilities + lifecycle
+├── {project_name} Deployment Architecture.md           ← Deployment topology
+├── XX_{component}_Design.md × N                        ← One per component, with the AI Quick Reference table
+├── XX_{project_name}_Core_API_Product_Code_Mapping.md  ← Product constraint → code location bridge document
+├── XX_{project_name}_Product_Rules_Cheat_Sheet.md
+├── XX_{project_name}_Business_Development_SOP.md
+├── {anti-patterns / RPC contracts / troubleshooting notes} × N
+├── _manifest.json                      ← Machine-readable manifest (for later graph merging)
+└── graph/                              ← Graph RAG graph document set
+    ├── G1 Component dependency matrix
+    ├── G2 Call chain overview + state machines
+    ├── G3 Data flow and storage dependencies
+    ├── G4 Error code component map
+    ├── G5 Cross-component interaction scenarios (≥10 sequence diagrams)
+    ├── G6 Knowledge graph triples (≥100 entries, with confidence)
+    ├── G7 Architecture risks and impact analysis
+    ├── G8 Core config parameter index
+    └── G9 Business rule constraint matrix + AI reasoning decision tree
+```
+
+---
+
+## Execution flow
+
+```
+Phase 0  → Initialisation: collect paths, project name, product doc sources; optional CLI ast+heuristic structural baseline
+
+Phase K1 → Architecture reverse-engineering: key file extraction → layered analysis → component relation matrix
+                                              ⛔ Confirmation point ① Architecture understanding
+
+Phase K2 → Document generation (parallel batches):
+             Batches 1~4: Type-4 component documents (dispatched to parallel sub-agents)
+                                              ⛔ Confirmation point ② Document quality spot check
+             Batches 5~7: architecture overview + bridge documents + knowledge enhancement
+
+Phase K3 → AI-Native enhancement:
+             search-anchor + bidirectional links + retrieval routing rules
+             Graph RAG graph document set G1~G9 (three-state confidence labels)
+
+Phase K4 → Quality assessment:
+             validate_kb.py automatic checks
+             Whole-base accuracy audit ([UNVERIFIED] statistics + interface coverage)
+             Cross-document consistency check (contradiction detection + automatic fixes)
+             RAG retrieval spot check (7 question types)
+             AI end-to-end validation (10~15 standard questions + code trace-back)
+             Quality report generation
+```
+
+Supports `--update` incremental updates (based on a file hash cache, rerunning only changed components).
+
+---
+
+## File structure
+
+The files below ship with the CLI; `teamai skill path wiki` prints the directory that contains them (`{SKILL_DIR}` in this document).
+
+```
+{SKILL_DIR}/
+├── SKILL.md                                ← Main execution instructions (`teamai skill get wiki`)
+├── scripts/
+│   ├── scan_repo.py                        ← Repository scan helper
+│   └── validate_kb.py                      ← Knowledge base quality validation tool
+├── references/
+│   ├── overview.md                         ← This file
+│   ├── agents/
+│   │   ├── kb-doc-generator.md             ← Dedicated Agent for Type-1~8 document generation
+│   │   └── graph-rag-agent.md              ← Dedicated Agent for G1~G9 graph documents
+│   ├── methodology/
+│   │   ├── phase0-collection.md            ← Source material collection method
+│   │   ├── phase1-reverse-engineering.md   ← Architecture reverse-engineering method
+│   │   ├── phase2-document-types.md        ← Specification and quality standards of the nine document types
+│   │   ├── phase3-ai-enhancement.md        ← AI-Native enhancement method
+│   │   └── phase4-quality.md               ← Quality assessment checklist
+│   ├── phases/                             ← Execution steps of each Phase
+│   └── templates/
+│       └── project-overview.md             ← Knowledge base README template (with cognitive boundary declaration)
+```
+
+---
+
+## Quality standards
+
+| Dimension | Passing standard |
+|------|---------|
+| Coverage | ≥90% of P0 core components have documents |
+| Accuracy | [UNVERIFIED] < 15% |
+| Structural quality | Dead links = 0, search-anchor coverage ≥95% |
+| AI usability | RAG retrieval spot check accuracy ≥85% |
+| Relation trustworthiness | AMBIGUOUS relations < 10%, all listed for confirmation |

package/skill-data/wiki/references/phases/k1-reverse-engineering.md

@@ -0,0 +1,118 @@
+## Phase K1: Architecture Reverse-Engineering and Source Material Collection
+
+**Methodology**: `{SKILL_DIR}/references/methodology/phase0-collection.md` + `{SKILL_DIR}/references/methodology/phase1-reverse-engineering.md`
+
+### Step 1: Optionally run the scan script (recommended)
+
+```bash
+python3 "{SKILL_DIR}/scripts/scan_repo.py" <project_root> --depth 2 --top 10
+```
+Output: file statistics + key file discovery report + language distribution.
+
+### Step 2: Key file extraction
+
+Scan by priority (see phase0-collection.md for details):
+- **P0 required**: entry files, routes/handlers, workflow orchestration config, Proto/IDL
+- **P1 important**: database schema (DDL), constant / error code definitions
+- **P2 enhancement**: config files, test files (to understand expected behaviour)
+
+### Step 3: Architecture reverse-engineering (see phase1-reverse-engineering.md for details)
+
+- Bottom-up layering: leaf nodes (DB/MQ) → intermediate nodes (orchestration/scheduling) → root nodes (API entry points)
+- Three-layer penetration tracing: for ≥5 core APIs, complete the full call chain trace API entry → orchestration layer → service execution layer
+- Build the N×N component relationship matrix (annotate the communication method: RPC/MQ/DB)
+
+### Step 4: Generate the architecture analysis report
+
+Write to `_review/k1-architecture-map.md`:
+
+```markdown
+## Architecture Layers (≥4 layers)
+| Layer | Components | Core Responsibility | Code Repository |
+
+## Component Inventory
+| Component | Architecture Layer | **Repository** | Language | Criticality (P0/P1/P2) | Entry File | **Interface Check Type** |
+
+Interface check type values (ask the user to verify this column at confirmation point ①):
+  - `HTTP`    → API access layer, has HTTP/gRPC route registrations, requires interface count reconciliation
+  - `MQ`      → message processing layer, has MQ Consumer/Exchange declarations, Topic count is the baseline
+  - `RPC`     → internal service layer, has .proto / .thrift / IDL files, Method count is the baseline
+  - `NONE`    → scheduling / execution / data layer, no external interface, no interface count check
+
+## N×N Component Communication Matrix
+(values: RPC/MQ/DB/—, annotated with confidence [E]EXTRACTED/[I]INFERRED/[A]AMBIGUOUS)
+
+## Core Call Chains (≥5)
+(format: API(file:line) → orchestration layer(config:line) → service layer(handler:line) → DB(table))
+
+## Glossary
+| Internal Term | External / Product Term | Notes |
+
+## Uncertain Items (for manual confirmation)
+(relationships and inferences marked [A], with the reason for the uncertainty)
+(components whose interface check type is uncertain, marked [?], to be clarified by the user at confirmation point ①)
+```
+
+### Step 5: Interface inventory scan (run separately per check type)
+
+**Run only for components whose interface check type in k1-architecture-map.md is ≠ NONE**:
+
+```
+FOR each component with interface check type = HTTP:
+  Run a grep scan:
+    Go:   grep -rn "\.GET\|\.POST\|\.PUT\|\.DELETE\|router\.Handle\|@handler" <component_dir>
+    Python: grep -rn "@app\.route\|@router\.\|APIRouter\|include_router" <component_dir>
+  Record: component → HTTP interface count N (SCAN_CONFIDENCE: HIGH/MEDIUM)
+
+FOR each component with interface check type = MQ:
+  Run a grep scan:
+    grep -rn "Exchange\|Queue\|Topic\|consumer\|subscribe\|@KafkaListener" <component_dir>
+  Record: component → MQ Topic/Queue count N
+
+FOR each component with interface check type = RPC:
+  Parse the .proto / .thrift files:
+    find <component_dir> -name "*.proto" -o -name "*.thrift" | xargs grep "^rpc\|^service"
+  Record: component → RPC Method count N
+```
+
+Write the results to `_review/interface-inventory.json`:
+```json
+{
+  "ComponentA": {"type": "HTTP", "count": 13, "confidence": "HIGH"},
+  "ComponentB": {"type": "MQ",   "count": 5,  "confidence": "MEDIUM"},
+  "ComponentC": {"type": "RPC",  "count": 8,  "confidence": "HIGH"},
+  "ComponentD": {"type": "NONE", "count": 0,  "confidence": "—"}
+}
+```
+
+**When done**: update `current_phase` to `"phasek1_waiting_confirm"`.
+
+**⛔ Confirmation point ①**: wait for an explicit reply from the user. Do not proceed to the next phase automatically.
+
+Show the user:
+```
+Architecture analysis complete.
+
+Component inventory (N in total):
+  P0 core: [list]
+  P1 important: [list]
+  P2 auxiliary: [list]
+
+Interface scan results (for verification):
+  HTTP interfaces: ComponentA 13, ComponentB 7
+  MQ Topics:       ComponentC 5
+  RPC Methods:     ComponentD 8
+  Components without interfaces: ComponentE, ComponentF, ...
+
+AMBIGUOUS relationships (please clarify):
+  - The communication method of ComponentX → ComponentY is uncertain
+
+Please confirm (edit k1-architecture-map.md directly, then reply "continue"):
+  1. Are the architecture layers and P0/P1/P2 annotations correct?
+  2. Is the interface check type (HTTP/MQ/RPC/NONE) of every component accurate?
+  3. Are the interface scan counts reasonable? Clearly too few means something was missed; too many may mean test files were scanned.
+```
+
+After confirmation: update to `"phasek1_confirmed"` → Phase K2.
+
+---

package/skill-data/wiki/references/phases/k2-documents.md

@@ -0,0 +1,68 @@
+## Phase K2: Document Generation (batched parallel runs + mid-way quality confirmation)
+
+**Methodology**: `{SKILL_DIR}/references/methodology/phase2-document-types.md`
+
+### Generation order (dependency-chain driven, lower layers first)
+
+```
+Batch 1: data layer + basic execution layer Type-4 component documents   ← parallel
+Batch 2: resource / scheduling layer Type-4 component documents          ← parallel
+Batch 3: messaging / service layer Type-4 component documents            ← parallel
+Batch 4: API entry layer Type-4 component documents                      ← parallel
+           ⛔ Confirmation point ② ← manual spot check of component document quality
+Batch 5: architecture overview layer (Type-1 + Type-2 + Type-3) ← serial (depends on all layers above being complete)
+Batch 6: bridge documents (Type-5 + Type-6 + Type-7)            ← serial (depends on product documentation)
+Batch 7: knowledge enhancement (Type-8: anti-patterns / RPC contracts / troubleshooting) ← serial
+```
+
+### Execution flow for each batch
+
+Read `{SKILL_DIR}/references/agents/kb-doc-generator.md`, assemble the input package and launch:
+
+```
+component_list:    list of components / document types for this batch
+architecture_map:  full content of _review/k1-architecture-map.md
+repos:             repository list from _review/repo-manifest.json
+service_map:       service_map from progress.json
+output_dir:        <Phase 0>
+project_name:      <Phase 0>
+product_docs_dir:  <Phase 0, may be empty>
+methodology_dir:   {SKILL_DIR}/references/methodology/
+completed_docs:    kb_progress.components_done (skipped on resume from checkpoint)
+parallel_mode:     true (batches 1~4) / false (batches 5~7)
+```
+
+After each batch completes:
+- Append the completed components to `kb_progress.components_done`
+- Accumulate `accuracy_stats` (extracted from the self-check summary returned by the Agent)
+- Update `current_phase` to `"phasek2_batch_N"`
+- Show the token consumption and `[UNVERIFIED]` statistics for this batch
+
+### ⛔ Confirmation point ② (after batches 1~4 complete)
+
+Show the user:
+```
+{N} component design documents generated. Accuracy statistics:
+  Total claims: {N} | Verified: {N} | [UNVERIFIED]: {N} ({X}%)
+  AMBIGUOUS relationships: {N}
+
+Please spot-check 2~3 documents (the most complex components are recommended):
+  Path: <output_dir>/XX_<component>_Design.md
+
+Points to confirm:
+  1. Is the code entry point in the AI Quick Reference table precise down to the function name?
+  2. Does the core flow description match the actual code?
+  3. Is the [UNVERIFIED] ratio acceptable? (<15% recommended)
+
+If you find a systematic problem, describe it and I will adjust the strategy and regenerate.
+```
+
+Update `current_phase` to `"phasek2_waiting_confirm"`.
+After the user confirms, update to `"phasek2_confirmed"` and continue with batches 5~7.
+
+### After all batches complete
+
+Write `_review/k2-doc-list.md` (document list: path + size in KB + [UNVERIFIED] count + generation time).
+Update `current_phase` to `"phasek2_done"` → Phase K3.
+
+---

package/skill-data/wiki/references/phases/k3-ai-native.md

@@ -0,0 +1,121 @@
+## Phase K3: AI-Native Enhancement + Graph Document Set
+
+**Methodology**: `{SKILL_DIR}/references/methodology/phase3-ai-enhancement.md`
+
+### Step 1: Inject AI-Native elements
+
+Add to all generated documents (where the Phase K2 Agent did not add them completely):
+
+| Element | Requirement | Scope |
+|------|------|---------|
+| `search-anchor` | 5~15 keywords, first line after the title | All documents |
+| AI Quick Reference table | 10 dimensions, immediately after the title | All Type-4 component documents |
+| Bidirectional links | component ↔ main architecture, bridge ↔ component | All documents |
+| Retrieval routing rules | 4 routing rules + 4 priority levels | Technical architecture overview only |
+| QA pairs | 10~20 high-frequency questions + answer references | Chapter 9 of the technical architecture overview only |
+
+### Step 2: Graph RAG graph document set
+
+Read `{SKILL_DIR}/references/agents/graph-rag-agent.md`, assemble the input package and launch:
+
+```
+all_kb_docs_dir:  <output_dir>
+architecture_map: _review/k1-architecture-map.md
+doc_list:         _review/k2-doc-list.md
+project_name:     <Phase 0>
+output_dir:       <output_dir>/graph/
+methodology_file: {SKILL_DIR}/references/methodology/phase2-document-types.md
+```
+
+Generate G1~G9 (every relationship carries a mandatory three-state confidence annotation):
+
+| Graph Document | Question Solved | Confidence Requirement |
+|---------|---------|-----------|
+| G1 Component Dependency Matrix | "Who depends on X?" | EXTRACTED from explicit document descriptions |
+| G2 Call Chain Overview + state machine + constraint matrix | "Which modules does an API pass through?" | call chains EXTRACTED, inferred dependencies INFERRED |
+| G3 Data Flow and Storage Dependencies | "Where is the data stored?" | read/write relationships EXTRACTED |
+| G4 Error Code Component Map | "Which module does this error code belong to?" | EXTRACTED |
+| G5 Cross-Component Interaction Scenarios (≥10 sequence diagrams) | "How is the quota check done?" | sequences EXTRACTED, boundaries INFERRED |
+| G6 Knowledge Graph Triples (≥100) | "Who does A depend on indirectly?" | every triple marked E/I/A + score |
+| G7 Architecture Risks and Impact Analysis | "How big is the impact if X goes down?" | direct dependencies EXTRACTED, indirect INFERRED |
+| G8 Core Config Parameter Index | "How do I change configuration XX?" | EXTRACTED from config files |
+| G9 Business Rule Constraint Matrix + AI reasoning decision tree | "Can I do XX?" | rules EXTRACTED, inferences INFERRED |
+
+Also generate `<output_dir>/graph/README.md` (index + lookup-by-question-type table + retrieval routing suggestions).
+
+### Step 3: Cross-document consistency check
+
+**After the Graph RAG Agent finishes, the main agent performs this step itself (do not delegate to a sub-agent).**
+
+Purpose: detect contradictory descriptions between component documents, preventing inconsistencies such as "A says it calls B over RPC, B says it is called by A over MQ".
+
+```
+Step 3A: Build the "claim matrix"
+
+  For every Type-4 component document, extract relationship claims from **two levels**:
+  
+  Level 1: the "Upstream Components" and "Downstream Components" fields of the AI Quick Reference table
+  Level 2: call descriptions in the interface design and core flow sections of the body
+  
+  If level 1 and level 2 describe the same relationship differently → first record it as an "intra-document contradiction" (a higher-priority problem than header vs body)
+  
+  Extraction example:
+    ComponentX.md header claims: X→Y(RPC), X→Z(MQ)
+    ComponentX.md body claims:   X→Z(HTTP)  ← contradicts the header!
+    ComponentY.md header claims: Y←X(RPC), Y→Z(DB)
+    ComponentZ.md header claims: Z←X(HTTP), Z←Y(DB)
+
+Step 3B: Cross-compare
+
+  FOR each pair of components (A, B):
+    IF A.md claims "A→B over RPC" AND B.md claims "B←A over MQ":
+      → record contradiction: "A→B communication method inconsistent: A says RPC, B says MQ"
+    IF A.md claims "A→B" BUT B.md does not mention "called by A":
+      → record omission: "A claims to call B, but B's document does not mention being called by A"
+    IF a relationship in the G1 matrix differs from the component document claims:
+      → record deviation: "G1 matrix says A→B(RPC), but A's document says A→B(MQ)"
+
+Step 3C: Generate the consistency report
+
+  Write to `_review/k3-consistency-check.md`:
+
+  ```markdown
+  # Cross-Document Consistency Check Report
+
+  ## Contradictions (must fix)
+  | Component A | Component B | A's Description | B's Description | Contradiction Type |
+  |-------|-------|---------|---------|---------|
+  | X | Z | X→Z(MQ) | Z←X(HTTP) | Communication method inconsistent |
+
+  ## Omissions (recommended additions)
+  | Claimant | Referenced | Claim | Omission |
+  |--------|---------|---------|------|
+  | A | B | A→B(RPC) | B's document does not mention being called by A |
+
+  ## G1 Matrix Deviations (recommended alignment)
+  | G1 Matrix | Component Document | Deviation |
+
+  ## Statistics
+  - Contradictions: N (❌ must fix)
+  - Omissions: N (⚠️ recommended additions)
+  - G1 deviations: N (⚠️ need alignment)
+  - Consistent relationships: N (✅)
+  - Consistency rate: X%
+  ```
+
+Step 3D: Automatic fixes (unambiguous cases only)
+
+  IF contradictions > 0:
+    FOR each contradiction:
+      Trace back to the code: use Grep to find the actual call method (e.g. rpc.Call / mq.Publish)
+      IF the correct side can be determined → fix the description in the wrong side's document + update the G1 matrix
+      IF it cannot be determined → mark as AMBIGUOUS, leave for the user to confirm at the confirmation point
+    Recompute the consistency rate after fixing
+
+  IF contradictions = 0:
+    → skip fixing, go straight to Phase K4
+```
+
+**When done**: update `current_phase` to `"phasek3_done"` → Phase K4.
+
+---