@rryando/arcs 3.0.0

package/opencode/arcs/skills/brainstorming/visual-companion.md

@@ -0,0 +1,277 @@
+# Visual Companion Guide
+
+Browser-based visual brainstorming companion for showing mockups, diagrams, and options.
+
+## When to Use
+
+Decide per-question, not per-session. The test: **would the user understand this better by seeing it than reading it?**
+
+**Use the browser** when the content itself is visual:
+
+- **UI mockups** — wireframes, layouts, navigation structures, component designs
+- **Architecture diagrams** — system components, data flow, relationship maps
+- **Side-by-side visual comparisons** — comparing two layouts, two color schemes, two design directions
+- **Design polish** — when the question is about look and feel, spacing, visual hierarchy
+- **Spatial relationships** — state machines, flowcharts, entity relationships rendered as diagrams
+
+**Use the terminal** when the content is text or tabular:
+
+- **Requirements and scope questions** — "what does X mean?", "which features are in scope?"
+- **Conceptual A/B/C choices** — picking between approaches described in words
+- **Tradeoff lists** — pros/cons, comparison tables
+- **Technical decisions** — API design, data modeling, architectural approach selection
+- **Clarifying questions** — anything where the answer is words, not a visual preference
+
+A question *about* a UI topic is not automatically a visual question. "What kind of wizard do you want?" is conceptual — use the terminal. "Which of these wizard layouts feels right?" is visual — use the browser.
+
+## How It Works
+
+The server watches a directory for HTML files and serves the newest one to the browser. You write HTML content, the user sees it in their browser and can click to select options. Selections are recorded to a `.events` file that you read on your next turn.
+
+**Content fragments vs full documents:** If your HTML file starts with `<!DOCTYPE` or `<html`, the server serves it as-is (just injects the helper script). Otherwise, the server automatically wraps your content in the frame template — adding the header, CSS theme, selection indicator, and all interactive infrastructure. **Write content fragments by default.** Only write full documents when you need complete control over the page.
+
+## Starting a Session
+
+```bash
+# Start server with persistence (mockups saved to project)
+scripts/start-server.sh --project-dir /path/to/project
+
+# Returns: {"type":"server-started","port":52341,"url":"http://localhost:52341",
+#           "screen_dir":"/path/to/project/.arcs/brainstorm/12345-1706000000"}
+```
+
+Save `screen_dir` from the response. Tell user to open the URL.
+
+**Finding connection info:** The server writes its startup JSON to `$SCREEN_DIR/.server-info`. If you launched the server in the background and didn't capture stdout, read that file to get the URL and port. When using `--project-dir`, check `<project>/.arcs/brainstorm/` for the session directory.
+
+**Note:** Pass the project root as `--project-dir` so mockups persist in `.arcs/brainstorm/` and survive server restarts. Without it, files go to `/tmp` and get cleaned up. Remind the user to add `.arcs/` to `.gitignore` if it's not already there.
+
+**Launching the server by platform:**
+
+**Claude Code:**
+```bash
+# Default mode works — the script backgrounds the server itself
+scripts/start-server.sh --project-dir /path/to/project
+```
+
+**Codex:**
+```bash
+# Codex reaps background processes. The script auto-detects CODEX_CI and
+# switches to foreground mode. Run it normally — no extra flags needed.
+scripts/start-server.sh --project-dir /path/to/project
+```
+
+**Gemini CLI:**
+```bash
+# Use --foreground and set is_background: true on your shell tool call
+# so the process survives across turns
+scripts/start-server.sh --project-dir /path/to/project --foreground
+```
+
+**Other environments:** The server must keep running in the background across conversation turns. If your environment reaps detached processes, use `--foreground` and launch the command with your platform's background execution mechanism.
+
+If the URL is unreachable from your browser (common in remote/containerized setups), bind a non-loopback host:
+
+```bash
+scripts/start-server.sh \
+  --project-dir /path/to/project \
+  --host 0.0.0.0 \
+  --url-host localhost
+```
+
+Use `--url-host` to control what hostname is printed in the returned URL JSON.
+
+## The Loop
+
+1. **Check server is alive**, then **write HTML** to a new file in `screen_dir`:
+   - Before each write, check that `$SCREEN_DIR/.server-info` exists. If it doesn't (or `.server-stopped` exists), the server has shut down — restart it with `start-server.sh` before continuing. The server auto-exits after 30 minutes of inactivity.
+   - Use semantic filenames: `platform.html`, `visual-style.html`, `layout.html`
+   - **Never reuse filenames** — each screen gets a fresh file
+   - Use Write tool — **never use cat/heredoc** (dumps noise into terminal)
+   - Server automatically serves the newest file
+
+2. **Tell user what to expect and end your turn:**
+   - Remind them of the URL (every step, not just first)
+   - Give a brief text summary of what's on screen (e.g., "Showing 3 layout options for the homepage")
+   - Ask them to respond in the terminal: "Take a look and let me know what you think. Click to select an option if you'd like."
+
+3. **On your next turn** — after the user responds in the terminal:
+   - Read `$SCREEN_DIR/.events` if it exists — this contains the user's browser interactions (clicks, selections) as JSON lines
+   - Merge with the user's terminal text to get the full picture
+   - The terminal message is the primary feedback; `.events` provides structured interaction data
+
+4. **Iterate or advance** — if feedback changes current screen, write a new file (e.g., `layout-v2.html`). Only move to the next question when the current step is validated.
+
+5. **Unload when returning to terminal** — when the next step doesn't need the browser (e.g., a clarifying question, a tradeoff discussion), push a waiting screen to clear the stale content:
+
+   ```html
+   <!-- filename: waiting.html (or waiting-2.html, etc.) -->
+   <div style="display:flex;align-items:center;justify-content:center;min-height:60vh">
+     <p class="subtitle">Continuing in terminal...</p>
+   </div>
+   ```
+
+   This prevents the user from staring at a resolved choice while the conversation has moved on. When the next visual question comes up, push a new content file as usual.
+
+6. Repeat until done.
+
+## Writing Content Fragments
+
+Write just the content that goes inside the page. The server wraps it in the frame template automatically (header, theme CSS, selection indicator, and all interactive infrastructure).
+
+**Minimal example:**
+
+```html
+<h2>Which layout works better?</h2>
+<p class="subtitle">Consider readability and visual hierarchy</p>
+
+<div class="options">
+  <div class="option" data-choice="a" onclick="toggleSelect(this)">
+    <div class="letter">A</div>
+    <div class="content">
+      <h3>Single Column</h3>
+      <p>Clean, focused reading experience</p>
+    </div>
+  </div>
+  <div class="option" data-choice="b" onclick="toggleSelect(this)">
+    <div class="letter">B</div>
+    <div class="content">
+      <h3>Two Column</h3>
+      <p>Sidebar navigation with main content</p>
+    </div>
+  </div>
+</div>
+```
+
+That's it. No `<html>`, no CSS, no `<script>` tags needed. The server provides all of that.
+
+## CSS Classes Available
+
+The frame template provides these CSS classes for your content:
+
+### Options (A/B/C choices)
+
+```html
+<div class="options">
+  <div class="option" data-choice="a" onclick="toggleSelect(this)">
+    <div class="letter">A</div>
+    <div class="content">
+      <h3>Title</h3>
+      <p>Description</p>
+    </div>
+  </div>
+</div>
+```
+
+**Multi-select:** Add `data-multiselect` to the container to let users select multiple options. Each click toggles the item. The indicator bar shows the count.
+
+```html
+<div class="options" data-multiselect>
+  <!-- same option markup — users can select/deselect multiple -->
+</div>
+```
+
+### Cards (visual designs)
+
+```html
+<div class="cards">
+  <div class="card" data-choice="design1" onclick="toggleSelect(this)">
+    <div class="card-image"><!-- mockup content --></div>
+    <div class="card-body">
+      <h3>Name</h3>
+      <p>Description</p>
+    </div>
+  </div>
+</div>
+```
+
+### Mockup container
+
+```html
+<div class="mockup">
+  <div class="mockup-header">Preview: Dashboard Layout</div>
+  <div class="mockup-body"><!-- your mockup HTML --></div>
+</div>
+```
+
+### Split view (side-by-side)
+
+```html
+<div class="split">
+  <div class="mockup"><!-- left --></div>
+  <div class="mockup"><!-- right --></div>
+</div>
+```
+
+### Pros/Cons
+
+```html
+<div class="pros-cons">
+  <div class="pros"><h4>Pros</h4><ul><li>Benefit</li></ul></div>
+  <div class="cons"><h4>Cons</h4><ul><li>Drawback</li></ul></div>
+</div>
+```
+
+### Mock elements (wireframe building blocks)
+
+```html
+<div class="mock-nav">Logo | Home | About | Contact</div>
+<div style="display: flex;">
+  <div class="mock-sidebar">Navigation</div>
+  <div class="mock-content">Main content area</div>
+</div>
+<button class="mock-button">Action Button</button>
+<input class="mock-input" placeholder="Input field">
+<div class="placeholder">Placeholder area</div>
+```
+
+### Typography and sections
+
+- `h2` — page title
+- `h3` — section heading
+- `.subtitle` — secondary text below title
+- `.section` — content block with bottom margin
+- `.label` — small uppercase label text
+
+## Browser Events Format
+
+When the user clicks options in the browser, their interactions are recorded to `$SCREEN_DIR/.events` (one JSON object per line). The file is cleared automatically when you push a new screen.
+
+```jsonl
+{"type":"click","choice":"a","text":"Option A - Simple Layout","timestamp":1706000101}
+{"type":"click","choice":"c","text":"Option C - Complex Grid","timestamp":1706000108}
+{"type":"click","choice":"b","text":"Option B - Hybrid","timestamp":1706000115}
+```
+
+The full event stream shows the user's exploration path — they may click multiple options before settling. The last `choice` event is typically the final selection, but the pattern of clicks can reveal hesitation or preferences worth asking about.
+
+If `.events` doesn't exist, the user didn't interact with the browser — use only their terminal text.
+
+## Design Tips
+
+- **Scale fidelity to the question** — wireframes for layout, polish for polish questions
+- **Explain the question on each page** — "Which layout feels more professional?" not just "Pick one"
+- **Iterate before advancing** — if feedback changes current screen, write a new version
+- **2-4 options max** per screen
+- **Use real content when it matters** — for a photography portfolio, use actual images (Unsplash). Placeholder content obscures design issues.
+- **Keep mockups simple** — focus on layout and structure, not pixel-perfect design
+
+## File Naming
+
+- Use semantic names: `platform.html`, `visual-style.html`, `layout.html`
+- Never reuse filenames — each screen must be a new file
+- For iterations: append version suffix like `layout-v2.html`, `layout-v3.html`
+- Server serves newest file by modification time
+
+## Cleaning Up
+
+```bash
+scripts/stop-server.sh $SCREEN_DIR
+```
+
+If the session used `--project-dir`, mockup files persist in `.arcs/brainstorm/` for later reference. Only `/tmp` sessions get deleted on stop.
+
+## Reference
+
+- Frame template (CSS reference): `scripts/frame-template.html`
+- Helper script (client-side): `scripts/helper.js`

package/opencode/arcs/skills/caveman-commit/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: caveman-commit
+description: Use when writing git commit messages, especially when ARCS Caveman mode is active. Produces Conventional Commits with terse, intent-preserving prose. Subject ≤50 chars; body only when the "why" isn't obvious from the diff.
+---
+
+# Skill: caveman-commit
+
+## When
+
+Writing git commit messages. Terse, exact, Conventional Commits. Why over what.
+
+## Flow
+
+```mermaid
+flowchart TD
+    A[Read diff] --> B[Classify: feat/fix/refactor/perf/docs/test/chore]
+    B --> C["Write subject: type(scope): imperative ≤50"]
+    C --> D{Why obvious from diff?}
+    D -->|yes| E[Subject only — done]
+    D -->|no| F[Write body: why + context]
+    F --> G{Breaking/security/migration?}
+    G -->|yes| H[MUST include body]
+    G -->|no| E
+    H --> E
+```
+
+## Format Rules
+
+| Element | Rule |
+|---------|------|
+| Subject | `<type>(<scope>): <imperative>` ≤50 chars (hard cap 72) |
+| Types | feat, fix, refactor, perf, docs, test, chore, build, ci, style, revert |
+| Mood | Imperative: "add", "fix", "remove" — not past/present tense |
+| Body | Wrap 72 chars, bullets `-`, skip if subject self-explanatory |
+| Issues | End of body: `Closes #42`, `Refs #17` |
+
+## Never Include
+
+- "This commit does X", "I", "we", "now" — diff says what
+- AI attribution (unless explicitly requested)
+- Emoji (unless project history uses them)
+- Trailing period on subject
+
+## Always Include Body For
+
+- Breaking changes, security fixes (cite CVE), data migrations, reverts (name SHA)
+
+## Constraints
+
+- Output message as code block only — do not run `git commit`
+- "Stop caveman-commit" or "normal mode" → revert to verbose style

package/opencode/arcs/skills/code-agent/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: code-agent
+description: Use when the task is mostly clear (50-90%) with one or two open decisions that can likely be resolved by inspecting the repo — not fully bounded, not a blank-slate design problem
+---
+
+# Skill: code-agent
+
+## When
+
+Task is mostly clear (50-90%) but 1-2 decisions remain open — resolvable by inspecting the repo.
+
+## Flow
+
+```mermaid
+flowchart TD
+    A[Orient: arcs brief --lean --json] --> K[Knowledge: arcs knowledge search slug keywords]
+    K --> B[Search: arcs search slug keywords]
+    B --> C[Inspect repo — patterns, types, fixtures]
+    C --> D{Confidence score >=80?}
+    D -->|Yes| E[Implement — TDD for new behavior]
+    D -->|No, inferable| E
+    D -->|No, genuine ambiguity| F[Ask ONE targeted question]
+    F --> E
+    E --> G[Verify — affected tests + lint on changed files]
+    G --> H{Complexity expanded?}
+    H -->|No| I[Done]
+    H -->|Yes| J[Pause — state issue — offer brainstorming]
+```
+
+## Phase 0: Check Existing Knowledge
+
+Before investigating or implementing, check what the DAG already knows:
+
+```bash
+arcs knowledge search <slug> "<task-keywords>" --lean --json
+```
+
+Look for:
+- `kind: pattern` — existing conventions that apply to this change
+- `kind: gotcha` — known traps in this area
+- `kind: lesson` — prior learnings from similar work
+
+If relevant entries exist, incorporate their guidance. Don't rediscover what's already known.
+
+## Behaviour
+
+- Inspect repo before asking anything
+- Score self-confidence per `confidence-gate` before any code edit; <80% triggers explore/web recovery, not improvisation
+- Proceed on inferred defaults when repo makes it clear
+- Ask at most one targeted question (product direction, naming, breaking trade-off)
+- TDD for new non-trivial behavior; skip for structural changes covered by existing tests
+- Lightweight bullet plan only when 3+ files and sequencing matters
+- Verify scoped: lint + test only files you touched (full suite only if change is pervasive — shared types, config, build)
+
+## NOT for
+
+- Fully bounded, no decisions → `quick-dev`
+- Unclear/creative/design-shaping → `brainstorming`

package/opencode/arcs/skills/deep-pr-review/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: deep-pr-review
+description: Use when the user provides a GitHub PR link with a "deep review" trigger inside a locally cloned repo, to perform a thorough multi-dimensional code review grounded in ARCS DAG context, AGENTS.md conventions, and optional graphify coupling analysis, then post findings as inline GitHub review comments under explicit user gate
+---
+
+# Skill: deep-pr-review
+
+## When
+
+User gives a GitHub PR URL plus a "deep review" trigger inside the locally cloned repo of that PR. Reviewer-side workflow: read-only by default, posts to GitHub only after explicit user gate.
+
+> CLI: `arcs --commands --json` for discovery. Posting is user-gated. ARCS writes (optional knowledge harvest) run directly via the CLI.
+
+## Flow
+
+```mermaid
+flowchart TD
+    classDef bail fill:#ef4444,color:#fff
+
+    A[User: 'deep review' + PR URL] --> B[Gather phase — see Data Gathering section]
+    B --> C{cwd repo == PR repo?}
+    C -->|no| Z[Halt — wrong checkout]:::bail
+    C -->|yes| D{Label = wip/draft?}
+    D -->|yes| D1[Soften severity — flag as WIP]
+    D -->|no| D2[Standard severity]
+    D1 & D2 --> E[arcs context --audience=implementer --lean --json]
+    E -->|found| F[Load AGENTS.md + targeted arcs search]
+    E -->|missing| G[Degraded mode — heuristics only]
+    F --> H{Prior AI review exists?}
+    G --> H
+    H -->|yes| I[Diff against prior review commit_id only]
+    H -->|no| J[Use full PR diff]
+    I --> K[Pick adaptive rubric from diff context]
+    J --> K
+    K --> L{Diff size?}
+    L -->|huge >40 files OR >2000 lines| M[Force summary mode]
+    L -->|normal| N{graphify available?}
+    N -->|yes| O[Run affected/query on changed symbols]
+    N -->|no| P[Skip coupling check — note in report]
+    M --> Q[Aggregate findings + cite each]
+    O --> Q
+    P --> Q
+    Q --> R[Present report + 5 posting modes]
+    R --> S{User choice}
+    S -->|don't post| END1[Show report only]
+    S -->|post| T[gh api: review + inline comments]
+    T --> U{Recurring pattern surfaced?}
+    U -->|yes + opt-in| V[Propose knowledge:create]
+    U -->|no| END2[Done]
+    V --> END2
+```
+
+## Data Gathering (ONE PASS — no repeat `gh` reads)
+
+Run these three commands once at the start. Cache the results. All downstream steps read from cache — never call `gh repo view` or `gh pr view` again.
+
+```
+1. gh repo view --json name,owner                                                         → REPO
+2. gh pr view <number> --json number,title,body,author,labels,reviews,state,files,headRefName,baseRefName  → PR_META
+3. gh pr diff <number>                                                                    → DIFF
+```
+
+| Downstream need | Read from |
+|-----------------|-----------|
+| Repo-match check | `REPO.name`, `REPO.owner` |
+| WIP / draft check | `PR_META.labels`, `PR_META.state` |
+| Author context | `PR_META.author` |
+| Prior review detection | `PR_META.reviews` |
+| File list / LOC delta | `PR_META.files` |
+| Diff text | `DIFF` |
+
+## Adaptive Rubric
+
+Agent picks dimensions from diff context. **Correctness is always evaluated.** Other dimensions activate when the diff signals them:
+
+| Dimension | Activates when |
+|-----------|----------------|
+| **Correctness** | Always — bugs, off-by-one, error handling, null safety |
+| **DRY** | New code resembles existing patterns; cross-module grep finds duplicates |
+| **KISS** | New abstraction layers, deep nesting, premature generalization |
+| **YAGNI** | Code written "for later" with no current caller; abstractions with one concrete use; configurable hooks with one known value; generic machinery built for hypothetical consumers |
+| **SOLID** | Module gains responsibilities, dependency direction shifts, large classes touched |
+| **Convention fit** | AGENTS.md or DAG `pattern`/`architecture` knowledge applies to changed files |
+| **Architectural risk** → handoff `architecture-review` | Diff crosses module boundaries, touches god nodes, changes public API |
+| **Performance risk** → handoff `performance-diagnosis` | Hot paths, loops over external IO, new queries, allocations in render |
+
+Skipped dimensions are reported as `cleared (not applicable: <reason>)`. Never silently dropped.
+
+## Severity Prefixes
+
+Reuses `caveman-review` format for inline output:
+
+| Prefix | Meaning | Posting default |
+|--------|---------|-----------------|
+| `🔴 bug:` | Broken behavior, will cause incident | Always post |
+| `🟠 risk:` | Works but fragile, edge case unhandled | Always post |
+| `🟡 suggestion:` | Concrete fix improving quality | Posted in modes 2/3 |
+| `🔵 nit:` | Style / naming / minor consistency | Posted only in mode 3 |
+| `❓ q:` | Genuine question for the author | Always post |
+
+## Posting Modes
+
+User picks one before any `gh` write:
+
+| # | Mode | What posts |
+|---|------|------------|
+| 1 | **Critical-only** | 🔴 bug + 🟠 risk + ❓ q only |
+| 2 | **Critical + actionable** | Above + 🟡 suggestion |
+| 3 | **All findings** | Above + 🔵 nit |
+| 4 | **Summary only** | Single top-level review body, no inline comments |
+| 5 | **Don't post** | Show report only — no `gh` calls |
+
+## Iron Law
+
+**READ ONLY until user picks a posting mode.** No `gh` writes, no ARCS writes, no auto-approve. Approval is only ever produced via explicit user override (`approve it`, `lgtm post approve`) — never inferred from finding count.
+
+## Citation Rule
+
+Every finding cites a source. No uncited findings:
+
+- `see knowledge/<id>: <title>` — ARCS knowledge entry
+- `AGENTS.md §<section>` — project convention
+- `graphify: <observation>` — coupling/affected result
+- `principle: <KISS|DRY|YAGNI|SOLID|correctness>` — first-principles label
+
+If only first-principles applies, that is sufficient — but it must be stated.
+
+## Inline Suggestion Rule
+
+GitHub `​```suggestion` blocks render an "Apply suggestion" button. Use **only** when the fix is a one-to-few-line replacement of existing lines on the diff. For larger fixes:
+
+- Multi-line code restructure → inline review comment with a fenced code block (no `suggestion` tag)
+- Missing block / new file content → top-level review body bullet
+- Cross-file refactor → handoff finding with `architecture-review` recommendation
+
+## Posting Protocol (ONE `gh api` call — never per-finding)
+
+All findings are batched into a **single** GitHub review submission. Never loop through findings and post each one individually.
+
+```
+gh api POST /repos/{owner}/{repo}/pulls/{number}/reviews \
+  --field commit_id="<PR head SHA from PR_META>" \
+  --field event="COMMENT" \
+  --field body="<top-level summary>" \
+  --field 'comments=[{"path":"...","position":N,"body":"..."},...]'
+```
+
+| Rule | Detail |
+|------|--------|
+| One call per review session | Top-level body + all inline comments in the same `comments[]` array |
+| Never mix `gh pr review` and `gh api` | Pick one entry point — use `gh api` for full control; `gh pr review` for body-only (mode 4) |
+| Never call `gh pr comment` after `gh api reviews` | `gh pr comment` adds a stand-alone comment, not a review — it will duplicate the top-level body |
+| Dry-run before sending | Print the full payload to the user for confirmation; only call `gh api` once user confirms |
+
+### Mode → command mapping
+
+| Mode | Command |
+|------|---------|
+| 1–3 (inline + summary) | `gh api POST .../reviews` with `body` + `comments[]` — **one call** |
+| 4 (summary only) | `gh pr review <number> --comment --body "..."` — **one call, no `comments[]`** |
+| 5 (don't post) | No `gh` writes |
+
+## Report Structure
+
+```
+# Deep PR Review: <repo>#<number> — <title>
+## Pre-flight (repo match, PR state, prior reviews)
+## Scope (files touched, LOC delta, modules affected)
+## Rubric Selection (which dimensions activated, why)
+## Findings (grouped by severity)
+## Cleared Dimensions (with evidence)
+## Architectural / Performance Handoffs (if any)
+## Posting Plan (mode chosen → exact comments to be posted)
+## Confidence & Gaps
+```
+
+## Constraints
+
+- **Never repeat `gh repo view` or `gh pr view` after the initial gather pass** — all data is cached upfront
+- **ONE `gh api` call to post the review** — batch all inline comments into the `comments[]` array; never loop and post per-finding; never mix `gh pr review` + `gh api` + `gh pr comment` in the same session
+- Never auto-approve; approval only on explicit user override
+- Never post to GitHub before user picks a posting mode
+- Cite every finding — no uncited claims
+- ` ```suggestion ` blocks only for small line-replacement fixes
+- Defer to `architecture-review` for full structural drift; surface as handoff flag, do not run inline
+- Defer to `performance-diagnosis` for perf investigation; surface as risk flag
+- Compose with `auditing-a-feature` rubric and `caveman-review` inline format — do not duplicate
+- Re-review detection: if AI has reviewed before, scope to diff since last review's commit_id
+- Tag each posted suggestion with `<!-- arcs:deep-review:<finding-id> -->` for re-review tracking
+- See `review-template.md` for GitHub review body template
+- See `graphify-diff.md` for the changed-symbols-to-affected algorithm

package/opencode/arcs/skills/deep-pr-review/graphify-diff.md

@@ -0,0 +1,102 @@
+# Graphify Diff Algorithm
+
+`graphify` has no native "diff against PR" command. This file defines how `deep-pr-review` builds coupling/duplication checks on top of the existing `affected`, `query`, and `diagnose multigraph` primitives.
+
+## Prerequisites
+
+```bash
+which graphify || echo "skip"            # graceful absence
+ls graphify-out/graph.json 2>/dev/null   # graph must exist
+```
+
+If graphify is missing or `graph.json` is older than the PR's base commit, refresh:
+```bash
+graphify update .
+```
+
+## Step 1: Extract changed symbols from the diff
+
+```bash
+gh pr diff <num> --patch > /tmp/pr.diff
+```
+
+Parse `/tmp/pr.diff` to extract changed symbols:
+- For each `+++ b/<file>` hunk, capture the file path
+- For each added / modified function or exported identifier, capture `<file>::<symbol>`
+- Skip pure deletions (handled separately under "removed coupling" check)
+
+Heuristic for symbol extraction (language-aware):
+- TypeScript / JavaScript: `function X`, `class X`, `export const X`, `export function X`, `const X = `
+- Python: `def X`, `class X`
+- Go: `func X`, `type X`
+- Rust: `fn X`, `struct X`, `impl X`
+- Other: fall back to file-level granularity
+
+## Step 2: Run `affected` per changed symbol
+
+```bash
+graphify affected "<file>::<symbol>" --depth 2 --json
+```
+
+Collect for each symbol:
+- **Fan-out callers** — who depends on this symbol (changes ripple here)
+- **Fan-out depth** — how many hops to leaves
+- **Cross-module edges** — callers in different top-level dirs
+
+## Step 3: Detect surprising fan-out
+
+Flag as 🟠 **risk** in the report when:
+
+| Pattern | Meaning |
+|---------|---------|
+| Changed symbol has >10 callers across >3 modules | Wide blast radius — non-obvious from diff alone |
+| Changed signature on a symbol with >5 callers | Breaking-change risk |
+| New symbol has same name as existing symbol in another module | Naming collision risk → DRY check |
+
+## Step 4: Duplication check
+
+For each new function added in the diff, run:
+```bash
+graphify query "functions similar to <new-symbol-signature>" --budget 8 --json
+```
+
+If results include symbols with similar signatures (≥70% name overlap or matching parameter shape), flag as 🟡 **suggestion** with citation `graphify: similar to <existing-symbol>` and propose extraction or reuse.
+
+## Step 5: Diagnose multigraph (architectural drift)
+
+```bash
+graphify diagnose multigraph --json
+```
+
+If the PR introduces edges that contribute to a multigraph collapse (multiple edges between the same node pair), flag as 🟠 **risk** with handoff to `architecture-review`. Same-endpoint multi-edges are a structural duplication signal worth surfacing but not worth diagnosing inline.
+
+## Step 6: Aggregate findings
+
+Each graphify-derived finding must include:
+- The `graphify` command that produced it (for reproducibility)
+- The cited symbol(s) — use backticks
+- The cited module path(s)
+- A finding ID for re-review tracking: `<file>:<line>:<dimension>:<short-hash>`
+
+## Performance bounds
+
+- Cap symbols analyzed per PR at 50. If diff contains more, sample by:
+  - All exported / public symbols first (always)
+  - Then internal symbols by descending hunk size
+- Skip step 4 (duplication) entirely if diff size exceeds 1500 LOC — too noisy
+- Skip step 5 (multigraph) if `graphify diagnose multigraph` runtime exceeds 10s — log and continue without
+
+## Graceful degradation
+
+If any graphify call fails or returns empty:
+- Note in report: `Graphify step <N> unavailable: <reason>` under "Cleared Dimensions"
+- Continue with the remaining dimensions
+- Never let a graphify failure abort the review
+
+## Output integration
+
+Graphify findings flow back into the standard finding pipeline. Each one is:
+- Cited as `graphify: <one-line observation>`
+- Severity-classified (most are 🟡 suggestion or 🟠 risk; rarely 🔴)
+- Attached to a specific file+line if possible; otherwise lives in the top-level review body
+- Tagged for re-review with `<!-- arcs:deep-review:<finding-id> -->`