|
| 1 | +Run a comprehensive code review using CKB's deterministic analysis + your semantic review. |
| 2 | + |
| 3 | +## Input |
| 4 | +$ARGUMENTS - Optional: base branch (default: main), or "staged" for staged changes, or a PR number |
| 5 | + |
| 6 | +## MCP vs CLI |
| 7 | + |
| 8 | +CKB runs as an MCP server in this environment. MCP mode is strongly preferred for interactive review because the SCIP index stays loaded between calls — drill-down tools like `findReferences`, `analyzeImpact`, and `explainSymbol` execute instantly against the in-memory index. CLI mode reloads the index on every invocation. |
| 9 | + |
| 10 | +## The Three Phases |
| 11 | + |
| 12 | +### Phase 1: CKB structural scan (5 seconds, 0 tokens) |
| 13 | + |
| 14 | +Call the `reviewPR` MCP tool with compact mode: |
| 15 | +``` |
| 16 | +reviewPR(baseBranch: "main", compact: true) |
| 17 | +``` |
| 18 | + |
| 19 | +This returns ~1k tokens instead of ~30k — just the verdict, non-pass checks, top 10 findings, and action items. Use `compact: false` only if you need the full raw data. |
| 20 | + |
| 21 | +If a PR number was given, get the base branch first: |
| 22 | +```bash |
| 23 | +BASE=$(gh pr view $ARGUMENTS --json baseRefName -q .baseRefName) |
| 24 | +``` |
| 25 | +Then pass it: `reviewPR(baseBranch: BASE, compact: true)` |
| 26 | + |
| 27 | +> **If CKB is not running as an MCP server** (last resort), use the CLI instead: |
| 28 | +> ```bash |
| 29 | +> ./ckb review --base=main --format=json |
| 30 | +> ``` |
| 31 | +> Note: CLI mode reloads the SCIP index on every call, so drill-down steps will be slower. |
| 32 | +
|
| 33 | +From CKB's output, immediately note: |
| 34 | +- **Passed checks** → skip these categories. Don't waste tokens re-checking secrets, breaking changes, test coverage, etc. |
| 35 | +- **Warned checks** → your review targets |
| 36 | +- **Top hotspot files** → read these first |
| 37 | +- **Test gaps** → functions to evaluate |
| 38 | +
|
| 39 | +### Phase 2: Drill down on CKB findings (0 tokens via MCP) |
| 40 | +
|
| 41 | +Before reading source code, use CKB's MCP tools to investigate specific findings. These calls are instant because the SCIP index is already loaded from Phase 1. |
| 42 | +
|
| 43 | +| CKB finding | Drill-down tool | What to check | |
| 44 | +|---|---|---| |
| 45 | +| Dead code | `findReferences(symbolId: "...")` or `searchSymbols` → `findReferences` | Does it actually have references? CKB's SCIP index can miss cross-package refs | |
| 46 | +| Blast radius | `analyzeImpact(symbolId: "...")` | Are the "callers" real logic or just framework registrations? | |
| 47 | +| Coupling gap | `explainSymbol(name: "...")` on the missing file | What does the co-change partner do? Does it actually need updates? | |
| 48 | +| Bug patterns | Already verified by differential analysis | Just check the specific line CKB flagged | |
| 49 | +| Complexity | `explainFile(path: "...")` | What functions are driving the increase? | |
| 50 | +| Test gaps | `getAffectedTests(baseBranch: "main")` | Which tests exist? Which functions are actually untested? | |
| 51 | +| Hotspots | `getHotspots(limit: 10)` | Full churn history for the flagged files | |
| 52 | +
|
| 53 | +### Phase 3: Semantic review of high-risk files |
| 54 | +
|
| 55 | +Now read the actual source — but only for: |
| 56 | +1. Files CKB ranked as top hotspots |
| 57 | +2. Files with warned findings that survived drill-down |
| 58 | +3. New files (CKB can't assess design quality of new code) |
| 59 | +
|
| 60 | +For each file, look for things CKB CANNOT detect: |
| 61 | +- Logic bugs (wrong conditions, off-by-one, race conditions) |
| 62 | +- Security issues (injection, auth bypass, data exposure) |
| 63 | +- Design problems (wrong abstraction, unclear naming, leaky interfaces) |
| 64 | +- Edge cases (nil inputs, empty collections, concurrent access) |
| 65 | +- Error handling quality (not just missing — wrong strategy) |
| 66 | +
|
| 67 | +### Phase 4: Write the review |
| 68 | +
|
| 69 | +Format: |
| 70 | +
|
| 71 | +```markdown |
| 72 | +## Summary |
| 73 | +One paragraph: what the PR does, overall assessment. |
| 74 | +
|
| 75 | +## Must Fix |
| 76 | +Findings that should block merge. File:line references. |
| 77 | +
|
| 78 | +## Should Fix |
| 79 | +Issues worth addressing but not blocking. |
| 80 | +
|
| 81 | +## CKB Analysis |
| 82 | +- Verdict: [pass/warn/fail], Score: [0-100] |
| 83 | +- [N] checks passed, [N] warned |
| 84 | +- Key findings: [top 3] |
| 85 | +- False positives identified: [any CKB findings you disproved] |
| 86 | +- Test gaps: [N] untested functions — [your assessment of which matter] |
| 87 | +
|
| 88 | +## Recommendation |
| 89 | +Approve / Request changes / Needs discussion |
| 90 | +``` |
| 91 | +
|
| 92 | +## Tips |
| 93 | +
|
| 94 | +- If CKB says "secrets: pass" — trust it, don't re-scan 100+ files |
| 95 | +- If CKB says "breaking: pass" — trust it, SCIP-verified API comparison |
| 96 | +- If CKB says "dead-code: FormatSARIF" — DON'T trust blindly, verify with `findReferences` or grep |
| 97 | +- CKB's hotspot scores are based on git churn history — higher score = more volatile file = review more carefully |
| 98 | +- CKB's complexity delta shows WHERE cognitive load increased — read those functions |
0 commit comments