hrt-adversarial-authoring

hrt-adversarial-authoring

Cross-context adversarial authoring: one subagent drafts, two further subagents — each with no memory of the author's reasoning, only the inputs they were given — challenge the draft from two orthogonal angles before it's accepted.

This skill is shared by two callers. The calling instruction MUST state which artifact is being authored — that choice fixes the draft content, both review checklists, and the resolution target below. Nothing else about the process changes between callers.

Parameters (set by the caller)

• artifact: specs or design. (proposal is not reviewed here: its grounding is the user's own interview answers, and it is checked by hrt-artifact-lint plus the user's read-and-confirm.)
• content_sections: the sections the draft subagent must produce.
  • specs: one spec file per capability listed in the proposal's Capabilities section — ### Requirement blocks with #### Scenario WHEN/THEN content, per the specs phase's format rules.
  • design: Context, Goals/Non-Goals, Decisions, Shape / Seams (when the change adds callable code), Risks/Trade-offs, Migration Plan, Open Questions, per the design phase's format rules.
• grounding_inputs: the artifacts the draft subagent may read.
  • specs: proposal.md, existing specs in openspec/specs/ (for capability naming).
  • design: proposal.md, specs/**/*.md.

Process

1. Draft. Spawn a subagent with only grounding_inputs and content_sections for the given artifact. It produces a draft only — no self-review, no hedging placeholders. Prose MUST follow the plain-language-writing skill's ARTIFACT rules while writing, not as a pass applied afterward. Output format: ## Draft (the artifact content) followed by ## Author Notes (open questions or assumptions the author flagged while writing).

2. Lint. The orchestrating session runs the hrt-artifact-lint skill and fixes every ERROR directly (deterministic, one correct fix each), so the reviewers spend no attention on grep/count structure. WARN lines go to the reviewers as context.

3. Review — two subagents, two orthogonal lenses, spawned concurrently, neither sees the other's output or the Author Notes. Each gets the post-lint draft and the same grounding_inputs the author had, but NOT the author's reasoning beyond ## Author Notes. Stay in your lane — the Critic owns content, logic, and decision quality; the Auditor owns the structural judgement calls; the lint owns counts and format. Don't duplicate or cross over.

   Thin-design shortcut (artifact: design only). If the post-lint draft's Shape / Seams body is exactly "no new code surface" AND Decisions has at most one entry with no rejected-alternative reasoning, run only the Destructive Critic — skip the Structural Auditor. A design.md this thin has nothing for the Auditor's judgement checks. Every Critic finding then surfaces to the user (the agreement auto-resolve path needs two reviewers), which is safe at this size. This does not apply to specs.

   Consequence gate (both reviewers). A finding reaches ## Required Changes only if it names what a reader or implementer concretely hits when it's unfixed (a misread claim, a blocked build, forced rework, an untested requirement). Critique that names no such consequence — "the premise is thin", "reads oddly" — goes to ## Suggested Improvements instead (non-blocking, no per-item question).

   • Destructive Critic (content and logic, checklist depends on artifact). Each finding names one concrete fact that would overturn it if true — a finding with none is not ready to report.
     • specs: does every claim trace to proposal.md? Anything asserted the grounding inputs don't support? Scope creeping past it? Assume the author is overconfident — look for what's missing or wrong, don't validate. The premise was settled in proposal.md — don't re-open it; a real premise error goes to ## Risks and Open Questions, not a Required Change.
     • design: a decision-quality review, not traceability — a Decision is right or wrong by whether its reasoning holds, not against a source doc. Premise, problem, and goals were settled upstream — don't re-argue them; a real premise error goes once to ## Risks and Open Questions. Per Decision: was a reasonable alternative dismissed without justification? Per Risk/Trade-off: is the mitigation actually sufficient, and is a plausible failure mode missing (premortem: assume it fails in production, work back to why)? Per seam: right boundary to test at, does it couple tests to an implementation detail, or does a higher existing boundary already cover it? For a Decision that creates a new module or seam, name one structurally different shape the author did not consider and say whether it is dominated; a decision with no such alternative needs no finding.
   • Structural Auditor (the structural judgement calls the linter cannot make — it does NOT re-check hashtag counts, checkbox format, section presence, or Covers: existence; the lint in step 2 owns those). Assume gaps exist until checked — finding nothing should be rare. Every Auditor finding here is UNANCHORED (it rests on interpreting intent):
     • specs: is every requirement genuinely testable — a measurable verb, unit, or condition, not just present but meaningful? Is every #### Scenario genuinely WHEN/THEN behavior, not an implementation detail dressed as one? Is a MODIFIED requirement carrying its full updated content, or has detail been dropped?
     • design: is an empty or N/A Migration Plan genuinely non-applicable, or is it hiding real deployment/rollback steps? Does each Decision's alternatives-considered rationale actually reason, or is it a placeholder? Is a "no new code surface" skip-line genuinely codeless? Does each seam signature describe a real boundary, or an invented one? Seams follow mattpocock's to-spec rule: tests attach at the highest available entry point, and fewer seams is better (ideal: one). Flag a seam that tests an internal collaborator, and several seams that one higher seam would cover.
   • Each reviewer's output format: ## Review Summary, ## Required Changes (each tagged ANCHORED with its grep/count, or UNANCHORED — Auditor findings are all UNANCHORED; each passes the consequence gate), ## Suggested Improvements (non-blocking: optional betterments, plus real findings that fail the consequence gate), ## Risks and Open Questions.

4. Resolve. The orchestrating session merges both reviewers' Required Changes (dedupe only same location + same complaint; never adjudicate between reviewers by LLM judgment). Classify each merged finding:

   • Auto-resolve (fix directly, no user prompt) if either holds: (a) ANCHORED — re-run the grep/count yourself to confirm before fixing; (b) both reviewers independently raised the same finding (true duplicate) — two independent lenses agreeing substitutes for a single reviewer's self-declared "this is safe." Record what changed.
   • Needs its own answer — any other finding that (i) changes scope proposal.md already settled, (ii) is a one-way door (a data migration or destructive schema change, deletion of stored data, a change to a published API or event contract, a config or flag removal other code reads, or a step that has to be undone by hand), or (iii) is a High-severity security trade-off. Show all of them together in one message. For each: the trade-off stated neutrally first, your recommendation second, so the user weighs the trade-off before seeing your answer. The user answers each one separately; a bare "ok" does not cover them. Apply only what they confirm or adjust.
   • Digest — everything else (every other single-reviewer UNANCHORED finding, plus Suggested Improvements, Risks and Open Questions, and the Author Notes). One message, after the findings that need their own answer are resolved: each finding with your recommended resolution and a one-line reason. "ok" accepts all of it; the user names any exception. Show at most 5 Suggested Improvements, strongest first, and say how many more were left out. An UNANCHORED finding from only one reviewer never auto-resolves, no matter how mechanical it looks: it waits in the digest for that "ok".
   • Both messages MUST follow the plain-language-writing skill's COMMS rules.
   • "Defer it" / "accept the drift" is not a real alternative — a finding whose only non-fix options are those is not a user decision. And a clean fix in hand doesn't make a finding auto-resolvable if a competent author could pick a different remedy.
   • For design, keep the existing bias: default more to the user than specs, even ANCHORED ones bordering on scope (these need their own answer) — decision-quality judgment is measurably less reliable than the lint's deterministic checks. The Destructive Critic's seam-boundary-quality check is UNANCHORED and goes to the digest, or to its own answer if it changes a seam that tests already depend on.

5. Finalize. Once Required Changes are resolved, write the artifact from the (possibly adjusted) draft using the phase's template.

If dark.md exists, the caller applies the hrt-dark-mode-routing skill to any finding that would otherwise surface to the user in step 4.

Fallback

If a subagent cannot be spawned, state that adversarial authoring could not be completed and ask the user whether to proceed with single-pass authoring. Do not silently skip a review step. If hrt-artifact-lint cannot run, its checks fall back to the Structural Auditor by hand — say so, do not skip them.