hermes-skills/create-plan/references/ask-claude-validation-template.md

# Ask-Claude Validation Template — `create-plan` Phase 4

> **This is the exact prompt + dispatch script the curator uses in Phase 4 to run the adversarial evidence-diff against `<topic>_plan.md` v2.** The curator fills in `<PLAN_BODY>` (full plan) and `<RESEARCH_CLAIMS_EXTRACT>` (~10KB cap) and dispatches to Claude Opus on 10.0.0.28. Output: a release-blockers / medium / low validation report. The curator applies agreed findings in Phase 6 — Claude does NOT rewrite the plan.

---

## 1. The Prompt (the exact text shipped to Claude)

The curator assembles this string, then writes it to a temp file (scp pattern — never inline in the SSH command; shell metacharacters in the plan body will break):

```
==== PLAN BEGINS ====
<PLAN_BODY>
==== PLAN ENDS ====

==== RESEARCH CLAIMS/CITATIONS EXTRACT BEGINS ====
<RESEARCH_CLAIMS_EXTRACT>
==== RESEARCH CLAIMS EXTRACT ENDS ====

You are reviewing an evidence-diff for a software plan. Below is:
1. The plan in full.
2. An extract of the structured claims, version numbers, official-URL
   citations, and key code/config snippets from the research evidence.

CRITICAL CONSTRAINT: Do NOT propose new features, new architecture, or new complexity.
Your job is to find FLAWS in what's already proposed — not to add more. If you find
a problem, say what's wrong and suggest the SIMPLEST fix.

YOUR JOB IS AN EVIDENCE-DIFF, NOT A VIBE CHECK.
For each claim the plan makes, check whether the provided research extract supports it.
For each claim in the provided research extract, check whether the plan addresses it.

Specifically report:
- Plan assertions that the research extract does NOT support (hallucinated claims)
- Major research extract findings the plan OMITS (silent gaps)
- Internal contradictions in the plan
- Missing TDD discipline (failing test before code-producing task?)
- Tasks larger than 2-5 minutes of focused work
- Missing official doc citations for tools the plan uses

Report format:
- Release-blockers (must fix)
- Medium (should fix)
- Low (nice to have)
- Pass-criteria met / not met

Do not rewrite the plan. Just report findings.
```

### 1.1 Note on Claude's capabilities / scope

Claude (Opus on 10.0.0.28) has **no web access** and cannot read the curator's local filesystem. Do NOT ask Claude to verify URL currency or file existence — those are the curator's job in Phase 5. Claude's job here is purely a structured text-vs-text diff against the inlined payloads.

### 1.2 Why "2-3 concrete suggestions" from the upstream pattern is dropped

The upstream `ask-claude` plan-validation prompt ends with "give 2-3 concrete suggestions for how to make this plan better." That suggestion-generating mode is **incompatible** with our CRITICAL CONSTRAINT (no new features, no new architecture, no new complexity). Suggestions would either be empty (waste of Claude's pass) or contradict the constraint. The template is deliberately narrower than the upstream pattern: pure flaw-finding, no improvement generation. If the operator wants improvement suggestions, that's a separate dispatch, not this validation pass.

### 1.3 Payload delimiters (must be present, exactly)

| Delimiter | Purpose |
|---|---|
| `==== PLAN BEGINS ====` ... `==== PLAN ENDS ====` | Wraps the full `<topic>_plan.md` v2. |
| `==== RESEARCH CLAIMS/CITATIONS EXTRACT BEGINS ====` ... `==== RESEARCH CLAIMS EXTRACT ENDS ====` | Wraps the extracted claims/citations section. |

The framing text and validation instructions follow BOTH delimiters (not inside the plan or research payload). Claude reads the instructions last and knows the markers are structural, not part of the text being reviewed.

---

## 2. The Research Payload — Size Discipline (MANDATORY)

The curator reads `<topic>_research.md` from disk and extracts **only the structured-claims/citations section**, not the full document. Inline that extract, not the full research.md.

**Extract these sections from `<topic>_research.md`:**
- Key Findings (claim + source URL pairs)
- Version Numbers & Currency Notes
- Official Documentation Citations
- Key Code / Config Snippets (verbatim — do not paraphrase)
- Conflicts / Open Questions

**Skip these sections:**
- The narrative Summary (Claude cannot verify prose; the curator's self-review, Phase 3, already covered it)
- Any other long-form discussion paragraphs

**Cap the inlined research payload at ~10KB.** Claude's context is not free, and a 50KB research.md will burn tokens on prose Claude cannot meaningfully diff against the plan anyway. The full research.md remains on disk for the curator's reference.

**Accepted trade-off:** Claude cannot detect findings in the research that live outside the extracted claims/citations (long prose paragraphs, narrative context, exploratory tangents). This is a known limitation, not a bug. The structured-claims extract is the load-bearing evidence; the curator's self-review (Phase 3) is the safety net for the rest. Document this trade-off in the final plan header so future readers know what Claude actually saw.

---

## 3. The Dispatch Script (parameterized, ready to run)

**CRITICAL: Use `write_file`, not `echo` or `$(cat)` — shell metacharacters in the plan body (backticks, `$`, quotes) will break the command.** The prompt template is in §1 above. Compose it with `write_file`, then scp + run:

```bash
# 1. Use write_file to create /tmp/curator-claude-prompt.txt
#    Compose the prompt from §1, substituting <PLAN_BODY> and <RESEARCH_CLAIMS_EXTRACT>
#    with the actual content. Do NOT use echo or $(cat) — use write_file.

# 2. scp the file to the remote
scp -i ~/.ssh/id_ed25519 -o StrictHostKeyChecking=accept-new -o ServerAliveInterval=30 /tmp/curator-claude-prompt.txt n8n@10.0.0.28:/tmp/curator-claude-prompt.txt

# 3. Run ask.sh on the remote
RESP=$(ssh -i ~/.ssh/id_ed25519 -o StrictHostKeyChecking=accept-new -o ServerAliveInterval=30 n8n@10.0.0.28 '~/claude/hermes_support/ask.sh --qfile /tmp/curator-claude-prompt.txt')
echo "$RESP"
rm -f /tmp/curator-claude-prompt.txt
```

**Flag rationale (per `ask-claude` v2.6.1):**
- `-i ~/.ssh/id_ed25519` — required key
- `-o StrictHostKeyChecking=accept-new` — first-time host key trust without prompting
- `-o ServerAliveInterval=30` — Opus turns can run 45-90s; prevents silent SSH drop
- `ask.sh --qfile <path>` — file-based, no shell metacharacter issues; the wrapper handles mktemp snapshot + claude invocation + merge.py internally
- **Never use `--resume`** for this validation role — Claude is one-shot for the evidence-diff. Re-validation is a fresh dispatch.

---

## 4. Parse the Response (one-shot, not a resumed session)

`ask.sh` returns JSON. Extract the two fields that matter:

```bash
# Claude's findings text
RESULT=$(echo "$RESP" | python3 -c "
import sys, json
try:
    d = json.load(sys.stdin)
except:
    print('ERROR: non-JSON response'); sys.exit(0)
subtype = d.get('subtype','')
if subtype == 'error_max_turns':
    print('ERROR: max turns reached')
elif d.get('is_error'):
    print(f'ERROR: {subtype} - {d.get(\"result\",\"\")}')
else:
    print(d.get('result','(empty)'))
")

# session_id — CAPTURED but NOT USED to resume
# Per the rules: re-validation = fresh dispatch. The session_id is recorded for the
# audit log only. Do not pass --resume on any follow-up.
SID=$(echo "$RESP" | python3 -c "
import sys, json
try: print(json.load(sys.stdin).get('session_id',''))
except: print('')
")
```

**Mandatory spot-checks (run before applying anything):**

| Check | Field | If true, do what |
|---|---|---|
| JSON parsed cleanly | n/a | If non-JSON, treat as failure → §5 |
| `is_error: true` | top-level | Treat as failure → §5 |
| `subtype: error_max_turns` | top-level | Treat as failure → §5 (note: `is_error` is `false` on this one — must check `subtype` explicitly) |
| `subtype: error_budget` | top-level | Treat as failure → §5 |
| `result` field is empty string | top-level | Treat as failure → §5 |
| `result` field has Claude's findings | top-level | Run the disagreement scan (ask-claude §3.5) before applying |

**Do not resume the Claude session under any circumstance.** A fresh `ask-claude` dispatch is a one-shot for the evidence-diff role. If a re-validation is needed (e.g., the curator applied Phase 6 fixes and wants Claude to take another pass), that is a **fresh dispatch** with a fresh prompt, not `--resume <old_sid>`.

---

## 5. Failure Handling (one-liner behavior)

**If ask-claude is unreachable (10.0.0.28 down / network error / `error_budget` / `error_max_turns` / non-JSON / empty response):**

> Finalize the plan WITHOUT the adversarial pass. Append a header note to `<topic>_plan.md`:
> `"Adversarial validation skipped — ask-claude unreachable. Recommend manual review before building."`
> Continue to Phase 5 (if not `--no-research`) and Phase 6. Surface the skip in the final curator handoff so the operator knows the plan was not adversarially reviewed.

**Do not retry.** Ask-claude unreachability is a transport/infrastructure failure, not a prompt-quality problem. Retrying just burns curator turns. One skip, one header note, move on. The operator can manually re-run Phase 4 by resuming the curator.

---

## 6. Disagreement Scan (after Claude responds — MANDATORY before applying)

Per `ask-claude` v2.6.1 §3.5, run the disagreement scan on Claude's response **before** applying any of its findings. The curator classifies each item (release-blocker / medium / low) as:

- **Agree + will apply** → note for Phase 6 reconcile
- **Agree + will skip** → state explicitly WHY (overkill, environment constraint, contradicts brief, contradicts operator's standing rule, etc.). Never silently drop.
- **Disagree** → decide it's not worth a round-trip and state your reason. **Do not resume Claude to push back** — re-validation is a fresh dispatch. If the disagreement is load-bearing, the operator can resume the curator to escalate.
- **Web references requested** → for any Claude claim that is a tool version, API behavior, library status, compatibility statement, or "best practice" assertion AND Claude did not cite a source URL inline — treat the claim as unverified. The curator's Phase 5 URL re-verify covers currency; for factual claims that should have come from the inlined research extract but don't, that's a finding to record.
- **Internal consistency check** → does Claude's response contradict itself, or contradict a prior finding in this same Phase 4? If yes, note it but do not chase it down — flag in the plan header.
- **Silently dropped** → should be empty. If non-empty, that's a bug. Surface it in the Phase 6 handoff.

Include a brief disagreement-scan recap in the plan header (see `curator-framing-prompt.md` Step 6.2) so future readers see what was considered and rejected.

---

## 7. What the Curator Hands Off to Phase 6

After Phase 4 completes, the curator has:

1. Claude's raw response (the `result` field) — kept in the curator session for reference
2. The session_id — recorded for the audit log, **not** used to resume
3. The classified list of findings (release-blockers / medium / low) with per-item disposition from §6
4. The disagreement-scan output (for the plan header)

Phase 6 applies the agreed findings + any URL re-verify mismatches from Phase 5. Claude's role ends here.

---

**Pipeline position:** Phase 0 (dispatcher, brief) → Phase 1 (curator → deep-research) → Phase 2 (curator, assemble) → Phase 3 (curator, self-review) → **Phase 4 (curator → ask-claude, this template)** → Phase 5 (curator, URL re-verify) → Phase 6 (curator, reconcile).