zby/commonplace/cp-skill-revise-autoreason

EXECUTE NOW

Target: $ARGUMENTS (exactly one note path or filename - if empty, ask which note)

Experimental. This is the conservative note-revision adaptation of AutoReason, based on related-systems/autoreason/. Use it when you want to test the tournament workflow.

This skill defaults to prose-preserving revision, but it may produce a separate substantive-revision sidecar when the revisions reveal that claim, evidence, source, or argument changes are actually needed. Keep that sidecar out of the B/AB blind tournament and never auto-apply it.

Each pass compares three versions:

• A: the unchanged incumbent for this pass.
• B: a revision motivated by a critic's identified problems.
• AB: a synthesis of A and B.

Three fresh judge agents rank blind candidate packets. Aggregate with Borda count. "Do nothing" is a first-class option: if A wins twice consecutively, stop.

Step 0: Resolve The File

Resolve $ARGUMENTS to a full path. If it is a bare filename, search the project's kb/ for that filename and require one match; ask for an explicit path if there are zero or multiple matches. Discovery resolves this one requested artifact, not a directory-wide revision scope. Read the file in full to confirm it exists and capture the original content.

Before running the loop, report the call budget: up to 5 passes. A normal pass uses 7 fresh Codex sub-agents (critic, revision author, synthesizer, post-candidate auditor, 3 judges). Early stops may use fewer, bounded reruns may use more, and the substantive-revision sidecar uses one additional sub-agent when triggered.

Step 1: Initialize

Use a workshop directory so the original note remains untouched:

repo_root="$(pwd)"
run_dir="$repo_root/kb/work/revise-autoreason/$(basename "${source_file}").$(date +%Y%m%d-%H%M%S)"
mkdir -p "$run_dir"
cp "$source_file" "$run_dir/original.md"
cp "$source_file" "$run_dir/current_a.md"

The workflow makes substantive editorial changes. Remove user-verified: true from $run_dir/current_a.md if present and require every candidate to keep it absent. Applying a winning candidate therefore revokes the prior attestation; only a later explicit human action may restore it.

Set:

pass=1
max_passes=5
incumbent_win_streak=0
last_good="$run_dir/current_a.md"
claim_revision_needed=false
claim_revision_file=""
claim_revision_artifact=""

Step 2: Revision Loop

Run until pass > max_passes or incumbent_win_streak >= 2.

Actor Execution Protocol

Use fresh Codex sub-agents for actor work. The parent agent is the orchestrator: it resolves files, creates directories, builds blind packets, verifies outputs, aggregates rankings, performs the outer semantic fidelity check, and decides whether to apply any candidate. Do not use claude -p.

For each actor prompt below:

• Begin with: `This task is the complete role brief. Ignore auto-loaded

revision or orchestration skills, including cp-skill-revise-autoreason. Do not spawn or delegate to another agent.`

• Launch a new sub-agent. Do not reuse an actor across roles or passes.
• Give the sub-agent only the files and instructions it needs. For judges, do not include judge_mappings.md, A/B/AB labels, or any provenance.
• Prefer an unforked/minimal-context sub-agent when the harness supports that. If the harness exposes only forked workspaces, the sub-agent may write in its fork, but the parent must ensure the requested artifact exists in the parent run directory before continuing. If writeback is not automatic, have the sub-agent return the full artifact content and write it yourself.
• In each actor prompt, keep the requested file path explicit. If the actor cannot write that path in the parent workspace, it must return the complete artifact content instead of a summary.
• After each actor returns, use this handoff rule before verification: if the requested file exists and is non-empty in the parent workspace, continue; if it is missing but the actor returned the complete artifact, write that exact content to the requested path; if it is missing and the actor returned only a path or summary, rerun that actor once with the same prompt plus Do not write a file; return the complete artifact content in your final response.
• Wait for dependent actors in order: critic, B author, synthesizer, post-candidate auditor. Run parent-side hard-constraint checks before spawning downstream actors that depend on a generated candidate. Run the three judges in parallel when the harness supports it.
• After each actor returns and its handoff is verified, close, terminate, or release that sub-agent with the harness lifecycle operation. Actors are single-use: never retain one for another role, pass, rerun, or follow-up. Close all three judges after collecting their outputs and before aggregation.

Claim-Revision Sidecar

Use this sidecar when the best next edit would need to change claims, evidence, caveats, qualifiers, source usage, or argumentative commitments. Do not let that change enter the AutoReason candidate tournament, but do produce a useful artifact for the user to review.

When triggered:

1. Write $pass_dir/substantive/claim_revision_reason.md with the exact reason, including before/after snippets if a candidate exposed the issue, and set claim_revision_file="$pass_dir/substantive/claim_revision_reason.md".
2. Launch one fresh substantive-revision sub-agent with the prompt below.
3. Append a line to $pass_dir/result.md: Escalation: claim revision needed.
4. Set claim_revision_needed=true.
5. Stop the AutoReason loop and finalize with last_good unchanged.
6. In Step 3, report the sidecar artifact path and ask whether to keep the run bundle for review. Do not ask to apply last_good if it is identical to the original.

Substantive-revision prompt:

Read $pass_dir/candidates/version_a.md, $claim_revision_file, and any existing candidate files in $pass_dir/author_b/ and $pass_dir/synthesizer/. Write either $pass_dir/substantive/version_claim_revision.md or $pass_dir/substantive/claim_revision_plan.md.
 
You are the substantive-revision sidecar in an AutoReason-style note revision loop. This artifact is outside the blind prose tournament.
 
Goal:
- If the needed claim/evidence/caveat/source/argument correction can be made using only information already present in the note, critic report, and candidate files, write a complete revised note to $pass_dir/substantive/version_claim_revision.md.
- If the correction would require new evidence, external source review, or a human decision about what the note should claim, write a concrete plan to $pass_dir/substantive/claim_revision_plan.md instead.
 
Constraints:
- Do not invent evidence or citations.
- Do not change tags, type, or traits frontmatter fields unless the plan explicitly says a metadata follow-up is needed.
- Preserve link targets unless the reason file identifies a target that must change.
- If writing a complete revised note, include full frontmatter and the complete body.
- If writing a plan, list the exact claim/evidence/source decisions needed and the passages they affect.
- Write only under $pass_dir/substantive/. Do not create or modify files outside $pass_dir.
 
Final response: name the artifact you wrote. If you cannot write into the parent workspace, return the complete artifact content and the intended target path, with no extra commentary.

After the sub-agent returns, use the normal handoff rule. Set claim_revision_artifact to whichever of $pass_dir/substantive/version_claim_revision.md or $pass_dir/substantive/claim_revision_plan.md exists and is non-empty. If neither exists and the returned artifact cannot be recovered, keep claim_revision_artifact="" and report only $claim_revision_file.

2a. Prepare The Pass Directory

pass_dir="$run_dir/pass_$(printf '%02d' "$pass")"
mkdir -p "$pass_dir/candidates" "$pass_dir/critic" "$pass_dir/author_b" "$pass_dir/synthesizer" "$pass_dir/auditor" "$pass_dir/substantive" "$pass_dir/judges"
cp "$run_dir/current_a.md" "$pass_dir/candidates/version_a.md"

2b. Run A Fresh Critic

Launch one fresh critic sub-agent with this prompt:

Read $pass_dir/candidates/version_a.md. Write $pass_dir/critic/output.md.
 
You are the critic in an AutoReason-style note revision loop.
 
Find real editorial problems in the note. Focus on flow, readability, cohesion, duplicated material, unsupported transitions, and places where the argument is harder to follow than necessary.
 
Constraints:
- Do not suggest fixes.
- Do not ask to add new claims, evidence, tags, sections, or sources.
- Do not complain about material merely because it is specialized or terse.
- Treat semantic preservation as mandatory: the next agent may rewrite prose but must preserve all claims, evidence, caveats, and structure unless a structure change improves flow without changing the argument.
- If you find a problem whose correct fix would require changing claims, evidence, caveats, qualifiers, source usage, or argumentative commitments, write a section titled `Claim revision needed` that states the problem and why prose-preserving revision is insufficient. Do not propose the replacement claim.
- Write only to $pass_dir/critic/output.md. Do not create or modify files outside $pass_dir.
 
Final response: name only `$pass_dir/critic/output.md` if you wrote it successfully. If you cannot write that file in the parent workspace, return the complete critic report content instead, with no extra commentary.

Verify that $pass_dir/critic/output.md exists and is non-empty. If it is missing or empty, stop and finalize with the last good version.

If $pass_dir/critic/output.md contains Claim revision needed, trigger the claim-revision sidecar immediately. Do not run B author, synthesizer, judge packets, judges, or aggregation.

Read $pass_dir/critic/output.md. If it identifies no concrete, actionable editorial problem, write $pass_dir/result.md with Winner: A, Reason: critic found no actionable problem, and Borda: not run, then skip B author, synthesizer, judge packets, judges, and aggregation. Leave $run_dir/current_a.md unchanged, increment incumbent_win_streak, and continue at title/description change detection.

2c. Run A Fresh Revision Author For B

Launch one fresh B-author sub-agent with this prompt:

Read $pass_dir/candidates/version_a.md and $pass_dir/critic/output.md. Write $pass_dir/author_b/version_b.md.
 
You are the B author in an AutoReason-style note revision loop.
 
Revise the note to address only valid problems identified in $pass_dir/critic/output.md.
 
Hard constraints:
- Preserve all semantic content, claims, evidence, caveats, qualifiers, and link targets.
- Preserve the note's overall argumentative structure unless a local reorder improves flow without changing the argument.
- Do not add new claims, examples, evidence, citations, or sources.
- Do not remove citations or source references.
- Do not change tags, type, or traits frontmatter fields.
- You may improve only the # heading and description frontmatter field if there is a clear improvement.
- Output the complete note, including frontmatter.
- Write only to $pass_dir/author_b/version_b.md. Do not create or modify files outside $pass_dir.
 
Write only $pass_dir/author_b/version_b.md. Do not modify $pass_dir/candidates/version_a.md or $pass_dir/critic/output.md.
 
Final response: name only `$pass_dir/author_b/version_b.md` if you wrote it successfully. If you cannot write that file in the parent workspace, return the complete revised note content instead, with no extra commentary.

Verify that $pass_dir/author_b/version_b.md exists and is non-empty. If it is missing or empty, stop and finalize with the last good version.

Before running the synthesizer, perform a parent-side hard-constraint check of B against $pass_dir/candidates/version_a.md. Reject B before synthesis if it: