Review Proposal — Conversational Proposal Agent

This is the moment a finding an agent surfaced turns into a decision a person actually makes. Something — a leverage/proposal-generating skill, /propose, a pipeline run — files a proposal saying "here's what's wrong and here's what I'd do." This skill is what happens when the person says "review LP-001": load it, check whether this exact thing has already been decided before, and have a real back-and-forth — "what about this edge case," "prove it," "what if we don't fix this" — before they say dismiss, defer, or build it.

When invoked with a proposal id (e.g., /review-proposal LP-032), load everything needed to have an informed conversation about it.

Where proposals live: if you've set up your own store or API for this (see /alignment-harness:harness-setup), use it. Otherwise (default), proposals are files under the folder alignment-harness records proposals prints — one markdown or JSON file per proposal, named by its id (e.g. LP-032.md).

Step 1: Load Context (do ALL of these before speaking)

1. Read the proposal file:

   ls $(alignment-harness records proposals)/*{id}*.md 2>/dev/null
   

   (Or wherever you've configured proposals to be filed — an Obsidian vault, a repo folder, your own API.) Read the full file. Extract: title, score, what is actually happening to real people, what the code does, what should happen instead, and the verification commands.

2. Check for a prior decision on this exact thing:

   Local default: an append-only file, known-decisions.jsonl, in the folder alignment-harness records known-decisions prints. Grep it for the proposal's keywords:

   grep -i "{keywords from proposal title}" $(alignment-harness records known-decisions)/known-decisions.jsonl 2>/dev/null
   

   If you have your own API for this:

   curl -s "<your-api>/known-decisions/check?signal={keywords from proposal title}" -H "x-api-key: $YOUR_API_KEY"
   

   If a prior decision exists, surface it — this proposal may already have been reviewed and dismissed or deferred. Do NOT re-investigate dismissed items.

3. Search institutional knowledge: If you've set up institutional-memory search (/alignment-harness:harness-setup), run it with the proposal's key domain terms (e.g. "email bounce guard", "checkout fallback") to pull related context — past sessions, prior investigations. If it's not set up, say so and check what you can: git log --oneline --grep="<keyword>", and grep this repo's docs/notes.

4. Check for prior pipeline runs, if your project keeps them:

   ls <your project's pipeline-runs folder, if you have one> 2>/dev/null | grep -i "{topic keywords}"
   

   If a prior run exists for this domain and left behind verification output, read it — it may contain evidence already gathered.

5. Query an oracle, if you've set one up (if certainty < 80% on the domain): If you configured a NotebookLM oracle or similar in /alignment-harness:harness-setup, ask it "what principles apply to {the domain this proposal touches}?" If you haven't set one up, reason instead from this repo's docs, git history, and past sessions, and say plainly that no oracle is configured.

Step 2: Present the Brief (ONE paragraph)

After loading all context, present a SINGLE paragraph that covers:

• What the proposal says is wrong — in human terms, not code terms
• How confident you are it is real — cite evidence: real verification, code verification, or "code-only, certainty capped at 70%"
• What you would recommend (fix it, dismiss it, investigate more)
• Any relevant institutional knowledge or prior decisions

Example:

"LP-033 says two email sends bypass the bounce guard — one in the auth flow and one in urgent alerts. I verified both call sites exist in the code. No live-system evidence yet since triggering a real email send requires test accounts. Certainty: 70% (code-verified only). No prior decision exists on this. I'd recommend approving — it's a 15-minute fix with clear test criteria."

Wait for the person to respond. Do NOT continue without their input.

Step 3: Conversational Commands

The person talks to you. Respond to these patterns naturally — this is a conversation, not a form:

What they say	What you do
"what about {edge case}?"	Check the actual code for that edge case. Read the file. Report what you found, with file path and line number.
"is this actually broken?"	Attempt real verification — via /devtools-site-testing if you have it, or whatever browser/runtime verification tool you have. Show real evidence from the running product, not simulation.
"show me proof"	Load the actual product page or endpoint and capture evidence. Never simulate or describe what "should" happen.
"what if we don't fix this?"	Describe the impact of leaving it broken — who is affected, how often (cite the proposal's numbers), and what downstream features break.
"dismiss" / "this is fine" / "not a problem" / "skip it"	Ask for their reasoning in one sentence, then write the decision and update the file. See Step 4.
"build it" / "do it" / "greenlight"	Trigger greenlight flow. See Step 4.
"defer" / "later" / "not now" / "come back to this"	Mark as deferred. See Step 4.
"what's the score?"	Read the score from the proposal frontmatter and explain what the scoring dimensions mean for this specific proposal.
"how hard is this?"	Read the effort estimate from the proposal and translate to real terms: what files, what type of change, what could go wrong.

Step 4: After a Decision

Whichever way this goes, read the file back afterward and confirm the status actually changed. Silent write failures here are exactly what leaves a queue of undecided proposals nobody realizes is stuck.

On Dismiss

Ask: "What's the reasoning I should record for this?" (one sentence from them is enough)

Then:

1. Record the decision. Local default — append a line to known-decisions.jsonl:

   DIR="$(alignment-harness records known-decisions)"
   mkdir -p "$DIR"
   jq -nc --arg signal "{proposal title}" --arg decision "dismissed" \
     --arg reasoning "{their reasoning verbatim}" --arg proposalId "{LP-XXX}" \
     '{signal:$signal, signalKeywords:($signal|ascii_downcase|split(" ")), decision:$decision, reasoning:$reasoning, proposalId:$proposalId, sourceType:"pipeline-finding"}' \
     >> "$DIR/known-decisions.jsonl"
   

   If you have your own API: POST the same fields to your known-decisions endpoint.

2. Update the proposal file frontmatter: status: dismissed

3. Read the proposal file back — confirm status: dismissed is actually there.

4. Print: "Dismissed and recorded. No agent will re-investigate this unless the underlying code changes significantly."

---

On Greenlight

Invoke /review-proposal-greenlight with the proposal id and file path. That skill handles the full implementation dispatch.

Print: "Greenlighting {LP-XXX}. Creating a worktree and starting implementation."

---

On Defer

1. Record the decision the same way as Dismiss, with "decision": "deferred" and their reasoning if given (or "no reason stated").

2. Update the proposal file frontmatter: status: deferred

3. Read the file back to confirm.

4. Print: "Deferred. It will show in the review queue with a deferred tag."

Rules

• NEVER present a wall of text. The brief is ONE paragraph. Then stop and wait.
• NEVER simulate state you haven't actually checked. If you need to show proof, load the actual product.
• NEVER re-investigate a dismissed item unless the person explicitly asks.
• When uncertain about something specific, say exactly what you don't know and then CHECK IT before responding — don't leave the gap unfilled with hedged speculation.
• The conversation IS the approval gate. No forms, no buttons, no ceremony. Just talk.
• Confidence in the brief is about the EVIDENCE you have, not your ability to implement the fix.
• If there's no proposal by that id yet, say so plainly: "I don't see a proposal by that name yet — proposals get filed when an agent finds something worth reviewing, or you can describe one now and I'll write it up in the same format." Never invent one.