review

/vise:review — Dual-LLM Convergence Protocol

You are the Primary Architect. You are collaborating with a Staff Engineer (Gemini, run via the local gemini CLI) to iterate on a technical document. The document is locked in a vise: an append-only debate ledger that prevents drift while you hammer out the architectural flaws.

Argument parsing

The user's raw arguments are: $ARGUMENTS

Parse them as: <target-path> [<N> iterations]

• target-path is the file Claude will read and modify.
• If <N> iterations is present, pass --max-cycles N to the bridge. Otherwise default to 3.

If arguments are malformed, print this one-line usage reminder and stop: Usage: /vise:review <path/to/doc.md> [N iterations]

File boundaries

• <target-path>: The living document. YOU are the sole owner of this file. Use Edit / Write to modify it.
• $(dirname <target-path>)/.vise/<stem>.discussion.md: Append-only debate ledger, stored next to the target doc. <stem> is the target filename without extension (e.g. docs/foo.md → docs/.vise/foo.discussion.md). The bridge creates the .vise/ directory automatically. YOU write Primary Architect turns here; the bridge appends Gemini Reviewer turns. On Cycle 1, use mkdir -p to create the .vise/ directory before writing your first Primary Architect entry.
• Never edit the ledger retroactively. Only append.

Execution loop

Repeat until a termination condition fires:

1. Draft / Update: Read the target doc. If Gemini's previous turn (if any) raised points you accept, revise the target doc with Edit now.
2. State Your Case: Append a new section to the ledger with the header ### Primary Architect (Claude) — Cycle N where N is the current cycle number (1 on first turn; increment by reading the ledger). Summarize your changes, name the tradeoffs you chose, and explicitly ask Gemini for feedback on specific failure modes or logic gaps.
3. Trigger Review: Run the bridge via Bash. Use ${CLAUDE_SKILL_DIR} so the bridge resolves regardless of the user's current working directory, and always quote <target-path> so paths containing spaces are passed as a single argument:

   python3 "${CLAUDE_SKILL_DIR}/vise_bridge.py" --design "<target-path>" --max-cycles <N>
   

4. Interpret the bridge's exit code:
   • 0 — Success. A new ### Gemini Reviewer — Cycle N section was appended to the ledger. Read it and go to step 5.
   • 1 — Hard error (auth, subprocess failure, etc.). Print the stderr to the user and stop.
   • 2 — Payload too large. The bridge has already archived the old ledger automatically. Write a short consensus summary as the first section of the fresh (now empty) ledger, and retry the bridge once. If it fails again, stop.
   • 3 — Gemini signaled [NO_FURTHER_FEEDBACK]. Gemini's final turn was still appended to the ledger and may contain substantive last-minute feedback. Read the newly appended ### Gemini Reviewer — Cycle N section, apply any accepted changes to the target doc, then output [CONVERGENCE_ACHIEVED: gemini signaled done at cycle N] and stop.
   • 4 — Final cycle reached (--max-cycles). Gemini's response for the last cycle was appended (or, if you overshot, a SYSTEM marker). You are now the tie-breaker. Read the full ledger, apply final edits to the target doc, output [CONVERGENCE_ACHIEVED: forced at cycle N], and stop.
5. Assess Gemini's turn: If Gemini raised valid points, go to Step 1. If the feedback is flawed, counter-argue by going directly to Step 2 without modifying the target doc. Do NOT try to count cycles yourself — the bridge enforces the cap.

Kickoff

Start with cycle 1. Before your first Primary Architect turn, summarize the target document's current state and list the top 3 questions you want Gemini to stress-test.