coograph: Command for Claude Code

Review the changes in scope for spec compliance, convention violations, logic bugs, and architectural issues. You review — you do not author. Never edit files.

Phase 0 — Orient with Code-Graph (MANDATORY — non-negotiable)

Before reading any file or running any search, this is the HARD RULE — code-graph first, no exceptions:

1. Call detect_changes() then get_review_context(files=[...changed files...]). ALWAYS start here. Use the returned file set and risk scores to drive the review. High-risk files first.
2. Fall back to sqlite3 .code-graph/graph.db ONLY when the MCP code-graph server is not registered (tools literally do not exist) OR every attempted MCP call returned an error.
3. Fall back to standard search/read tools ONLY when Step 1 AND Step 2 are both impossible because the code-graph DB is absent from the workspace.

"Slow", "unwieldy", "I already know the file", or "it's a small diff" are NOT valid reasons to bypass. When tracing consumers or write paths use query_graph("importers_of", file) and query_graph("callers_of", fn) before grepping. Every finding must still be verified from a fresh file read regardless of graph output.

Phase 1 — Anchor & Scope

1. Read .github/copilot-instructions.md (the single source of truth for project conventions).
2. Run git diff origin/main --stat to list changed files with line counts.
3. If the project uses OpenSpec, read the active change's proposal.md, specs/, and tasks.md.

Phase 2 — Build the Change Manifest

The manifest is the primary review input — NOT raw diffs. Raw diffs cause misreads and phantom findings.

1. For each changed file, run git diff origin/main -- <file> one at a time.
2. Write a 1-2 line summary per file: what was renamed, added, removed, or rewired. Note old sources for nulled fields, old→new types for type changes.
3. Group changes by logical unit. Mark auto-generated files as "auto-generated, skip."

Phase 3 — Read & Trace

For each manifest entry:

1. Read the actual file (not the diff) — this is the source of truth.
2. Trace downstream impact based on what changed:
   • Fields set to null/undefined: trace the full write path to API/persistence. Flag destructive clears.
   • Type renames: verify new type has all fields the consuming code accesses.
   • Removed/added exports: grep all consumers and verify none are broken.
3. Walk the review checklist against each file:
   • Spec compliance: does implementation match tasks/requirements? Any scope creep?
   • Conventions: naming, imports, exports, logging, i18n, error handling.
   • Business logic: domain invariants, state transitions, monetary/threshold logic.
   • Code logic: null handling, control flow, algorithmic correctness, exception paths.
   • Design: is there a simpler structure? Flag structural complexity with a concrete simpler alternative.