Review Proposal — Greenlight Implementation

Triggered when the person greenlights a proposal during a /review-proposal conversation. This skill turns a reviewed proposal into a PR.

Pre-flight Checks

Before writing a single line of code:

1. Read the proposal file in full to extract the implementation contract:

   • "What should happen instead" section = the intent
   • "Fix" or implementation section = the approach
   • "Verification" section = the completion criteria (these become the sprint contract)
   • "Dependencies" section = what else must be true

2. Verify the affected area currently works:

   • If the proposal touches a critical path for this project (payments, auth, the core feature, anything users depend on) — verify that path works right now, before you touch it.

   # Use whatever this project's own smoke test or health check is, if one exists.
   # Look for a documented one first (README, package.json scripts, CLAUDE.md).
   # If none is configured, say so plainly and proceed on the proposal's own
   # Verification section only — do not invent a health check that doesn't exist.
   npm test -- --testPathPattern=smoke 2>/dev/null || echo "no smoke test found — proceeding on the proposal's own verification section"
   

3. Flag if current functionality could break: If the fix touches a working critical path, say this before proceeding:

   "This touches {area}. {Area} currently works. The fix could break it if {specific condition}. Proceeding with {specific safeguard I will use}."

   Do NOT ask permission — state what you're doing and proceed unless the person says stop.

Sprint Contract

Before writing code, commit to this contract out loud:

• Scope: exactly what files will change and why
• Verification commands: the specific commands from the proposal's Verification section that will prove it works
• Exit criteria: what "done" looks like in the running product
• What must NOT change: any files outside the proposal's explicit scope

If the proposal has no Verification section at all, say you cannot form a sprint contract without knowing what "done" looks like, and ask for one sentence describing how to check the fix worked — before writing any code.

Implementation

1. Create a git worktree in this project's repository (not a separate copy — the repo you're already working in):

   git worktree add \
     .claude/worktrees/{proposal-id-lowercase} \
     -b fix/{proposal-id-lowercase}
   

   Work exclusively in this worktree — never touch the main branch files directly.

   If worktree creation fails: check if a worktree for this proposal already exists (git worktree list). If it does, use it rather than creating a duplicate.

2. Implement the fix following the proposal's "What should happen instead" and "Fix" sections:

   • Stay within the proposal's scope. If you discover a related issue, note it, but do NOT fix it here.
   • Follow this project's own coding standards (check CLAUDE.md or an equivalent conventions doc if one exists) — no swallowed errors, no missing returns on early exits, no unstructured logging where the project has a logger.

3. Run the verification commands from the proposal's Verification section. Read the output. Do not self-assess — report exactly what the commands returned.

4. Open the PR, if this project has a remote and gh is available:

   gh pr create \
     --title "{proposal title from frontmatter}" \
     --body "$(cat <<'EOF'
   ## What this fixes
   
   {The "What is actually happening to real people" section from the proposal, verbatim or closely paraphrased}
   
   ## Verification
   
   {The output from running the verification commands}
   
   Resolves: {proposal id}
   Proposal: {the file path this proposal lives at — the folder `alignment-harness records proposals` prints, unless the person configured a different store}
   EOF
   )"
   

   If gh isn't installed, isn't authenticated, or there's no pushable remote configured, say so plainly and stop at: "Implementation complete, verification {passed/failed as shown above}, no PR opened because {reason}." Never claim a PR exists without a real link, and never silently skip this step without saying you skipped it.

5. Update the proposal file: set status: greenlit in its frontmatter (in the folder alignment-harness records proposals prints, or the person's own store if they've set one up), then read the file back and confirm the status actually changed. Silent write failures here are exactly what leaves a proposal looking un-actioned when it wasn't.

6. Report back:

   "PR opened: {URL, or 'none — see reason above'}. {N} files changed. Verification: {pass/fail with the actual output you saw}. The proposal is marked greenlit."

Safety Rails

• NEVER touch files outside the proposal's explicit scope. Scope creep invalidates the proposal as a contract.
• NEVER remove existing functionality to make a fix simpler. Fix the actual error; don't delete the feature it lives in.
• NEVER force-push or skip tests. If tests fail, report exactly what failed — do not try to work around it.
• NEVER mark verification as "pass" without running the actual commands and reading the actual output.
• These safety rails are enforced by your own discipline in this skill, not by a separate mechanical check — treat them as load-bearing instructions, not suggestions.

When Implementation Uncovers a New Problem

Say exactly this structure:

"While implementing {proposal id}, I found {what the new problem is, in human terms}. This is outside the proposal's scope. I'm continuing with the original fix. I'll log the new finding as a candidate for a separate proposal."

Then continue implementing the original scope. If it's significant, file the new finding as a new proposal in the folder alignment-harness records proposals prints, following /proposal-schema.