@rryando/arcs 4.0.0 → 4.2.0

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

@@ -1,270 +1,12 @@
-# Visual Companion Guide
+# Optional Visual Companion
 
-Browser-based visual brainstorming companion for showing mockups, diagrams, and options.
+Use only when seeing an interaction or layout is materially clearer than discussing it in text and the user accepts the offer.
 
-The companion is loopback-only: it serves the local browser on the same machine and rejects non-loopback host configuration.
-
-## 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.
-
-`--host` and `--url-host` accept loopback names and addresses only. Remote/container port exposure is intentionally unsupported.
-
-## 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
+The companion is loopback-only. Do not expose it on a LAN or public interface.
 
 ```bash
-scripts/stop-server.sh $SCREEN_DIR
+node scripts/start-server.sh
+node scripts/stop-server.sh
 ```
 
-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`
+Present one focused mockup or choice at a time. Treat selections as design input, not permission to write code or durable artifacts. Stop the server when the visual discussion ends.

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

@@ -1,51 +1,14 @@
 ---
 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.
+description: Write a terse Conventional Commit message from an existing diff
 ---
 
-# Skill: caveman-commit
+# Caveman Commit
 
-## When
+Read the diff and output a commit message only; never run Git commands.
 
-Writing git commit messages. Terse, exact, Conventional Commits. Why over what.
+Format the subject as `type(scope): imperative`, preferably at most 50 characters and never over 72. Use a body only when the reason is not obvious, or for breaking changes, security fixes, migrations, and reverts. Wrap body lines at 72 characters.
 
-## Flow
+Use established project types and scopes. Avoid filler, AI attribution, emoji unless conventional, and a trailing subject period.
 
-```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
+Return only the message in a code block.

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

@@ -1,218 +1,36 @@
 ---
 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 codegraph coupling analysis, then post findings as inline GitHub review comments under explicit user gate
+description: Review a GitHub PR deeply and post only after explicit user confirmation
 ---
 
-# Skill: deep-pr-review
+# Deep PR Review
 
-## When
+## Boundary
 
-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.
+Remain read-only until the user confirms the exact posting mode and payload. Never auto-approve. Use one GitHub write for the final review.
 
-> CLI: `arcs --commands --json` for discovery. Posting is user-gated. Knowledge is proposal-only unless the user separately and explicitly authorizes that exact ARCS write.
+## Gather Once
 
-## Flow
+Cache repository metadata, PR metadata, and the diff once:
 
-```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{codegraph available?}
-    N -->|yes| O[Run impact/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| V[Propose arcs knowledge upsert in report — ARCS-write opt-in to apply]
-    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` |
-
-`codegraph-diff.md` receives this cached `DIFF` snapshot; it must not run a second diff fetch.
-
-## 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 to the tech-architect agent (structural audit) | Diff crosses module boundaries, touches god nodes, changes public API |
-| **Performance/incident risk** → handoff to the software-engineer agent in incident mode with systematic-debugging | Hot paths, loops over external IO, new queries, allocations in render |
-
-Skipped dimensions are reported as `cleared (not applicable: <reason>)`. Never silently dropped.
-
-## Over-engineering / bloat pass
-
-A focused pass that hunts ONLY over-engineering and complexity — correctness, security, and performance stay in the normal review pass above. Runs on a diff (delete-list for the changed lines) OR whole-repo (bloat audit). Lists findings only; applies nothing.
-
-One finding per line, tagged:
-
-| Tag | Catches | Replacement |
-|-----|---------|-------------|
-| `delete:` | Dead code, unused flexibility, speculative feature | nothing |
-| `stdlib:` | Hand-rolled thing the standard library ships | name the function |
-| `native:` | Dependency or code doing what the platform already does | name the feature |
-| `yagni:` | Abstraction with one implementation, config nobody sets, layer with one caller | inline / remove |
-| `shrink:` | Same logic in fewer lines | show the shorter form |
-
-Format: `L<line>: <tag> <what>. <replacement>.` — use `<file>:L<line>: ...` for multi-file or whole-repo audits.
-
-End with the only metric that matters: `net: -<N> lines, -<M> deps possible.` Nothing to cut → `Lean already. Ship.`
-
-Boundary: never flag the single runnable check that implementation minimalism requires for non-trivial logic as bloat.
-
-## Severity Prefixes
-
-Inline findings are one line — `<file>:L<line>: problem. fix.` — prefixed by severity:
-
-| 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
-- `codegraph: <observation>` — coupling/impact 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 recommending the tech-architect agent (structural audit)
-
-## 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":"..."},...]'
+```bash
+gh repo view --json name,owner
+gh pr view <number> --json number,title,body,author,labels,reviews,state,files,headRefName,baseRefName
+gh pr diff <number>
 ```
 
-| 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
+Verify the current checkout matches the PR repository. Reuse the cached diff for review and optional `codegraph-diff.md` analysis.
 
-| 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 |
+## Review
 
-## Knowledge Proposals (standard report output)
+Check correctness first, then activate only relevant dimensions: security, tests, compatibility, KISS/YAGNI/DRY, architecture, and performance. Cite every finding with a diff location and consequence. Large PRs may use summary mode.
 
-A recurring finding — the same class of bug, the same convention violation, a trap seen more than once across the diff — is durable knowledge, not just a one-off comment. Make proposing it a standard part of the report, not an afterthought. First use `arcs knowledge template --kind=<kind> --json`; then include a proposed `arcs knowledge upsert <slug> "<title>" --kind=<pattern|gotcha> --summary="<the recurring issue and the fix convention>" --body="<substantive filled template>" --keywords="<k1,k2>" --source-files="<path,...>" --json` in the report. Do not execute `arcs knowledge upsert` without explicit user authorization for that exact command. This opt-in is separate from the GitHub posting choice: a review that posts nothing can still surface knowledge proposals. Upsert is idempotent by title.
+Present findings and ask the user to choose: critical-only, actionable, all, summary-only, or do not post. Show the exact payload before confirmation.
 
-## Report Structure
+For inline modes, batch summary and comments into one `gh api POST .../reviews` call. For summary-only, use one `gh pr review --comment` call. Do not mix posting methods or post comments one by one.
 
-```
-# 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)
-## Knowledge Proposals (recurring findings → proposed arcs knowledge upsert, ARCS-write opt-in)
-## Architectural / Performance Handoffs (if any)
-## Posting Plan (mode chosen → exact comments to be posted)
-## Confidence & Gaps
-```
+Recurring knowledge is optional and separately authorized from GitHub posting.
 
-## Constraints
+## Return
 
-- **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 the tech-architect agent (structural audit) for full structural drift; surface as handoff flag, do not run inline
-- Defer performance or incident investigation to the software-engineer agent with `AGENT_MODE: incident` and mandatory systematic-debugging; surface as a risk flag
-- Review dimensions are defined in this skill (Adaptive Rubric); inline findings use the one-line format `<file>:L<line>: problem. fix.` — 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 `codegraph-diff.md` for the changed-symbols-to-impact algorithm
+Report scope, findings by severity, cleared risks, confidence/gaps, and the chosen posting result.