/harden-artifact

name: harden-artifact
description: Harden a REQUIREMENTS or PLAN document before the next phase picks it up — checked against its ticket, the code and related tickets, proven mistakes fixed in place.
disable-model-invocation: true
type: flow
license: MIT
metadata:
  version: "0.1"

Harden artifact

Make a `.REQUIREMENTS.md` or `.PLAN.md` — the **artifact** — safe to hand to the next phase: every deviation from its ticket deliberate, explained and correct; every claim true; nothing blocking the session that picks it up. A fresh-context reviewer hunts, the session challenges each finding, and only what survives changes the artifact — which **must never end worse than it started**.

A session that wrote the artifact cannot judge findings on it: say so and propose a fresh session before continuing.

Resolve the sources

• **Artifact** — the file the invocation names; ambiguous or neither kind → ask. A plan — the

artifact or one of the same base — with a ticked task is already being built, past where hardening belongs → say so and ask before going on.

• **Ticket** — the document the artifact was refined from, found by file name: the artifact's

suffix replaced by `.TICKET` (`FOO.PLAN.md` → `FOO.TICKET.md`), or, when the stem names another source, that file (`FOO.PR-REVIEW.REQUIREMENTS.md` → `FOO.PR-REVIEW.md`). A source with decisions recorded beside it (a PR review's `.ANSWERS.md`) is read with them: only what they accept is the ticket — the rest is out of scope, never a deviation, never recorded in the artifact. Ambiguous → ask; no file → ask whether the ticket lives elsewhere (a tracker id, pasted text) before treating it as none. None (e.g. requirements brainstormed from an idea) → say so: a plan is compared with its upstream instead; with neither, the review runs without the Deviations lens.

• **Upstream** (a plan only) — its name with `.PLAN` replaced by `.REQUIREMENTS`, when that

exists.

• **Related tickets** — those on disk: the ticket's `## Ticket set`, its parent, its siblings,

later ones that build on this work included.

• **Repos** — every repo the feature spans, as named by the ticket, the artifact and the project's

governing docs: where it is built, the other side of each integration it relies on, and whatever will consume what it delivers (a backend ticket's frontend, a library's apps, an API's other clients, the readers of a changed table). Any that can't be located → one batched ask for their paths, autoaccept or not; the user may skip one.

Done when the artifact, the ticket or its absence, and each repo's path or skip are settled.

Review

Load and follow [fresh-eyes-review](../fresh-eyes-review/SKILL.md) — inputs all explicit, so it runs without its confirmation step — with the whole artifact as the changeset, one sentence of intent (the ticket's title — without a ticket, the artifact's own summary — and the phase the artifact feeds), the sources above (skipped repos named as unavailable), and this mandate in place of its default:

• **Deviations.** List every difference between artifact and ticket (for a ticketless plan, its

upstream) in what must be true when the work is done — dropped, added, changed; rewording and merged duplicates are not differences, nor is a plan's "how". Each needs a written reason, anywhere in the artifact or its upstream: none → a finding. A reason is itself a claim.

• **Claims.** Every decision and factual statement is a claim to test, never accepted because it

is written. Probe each source class:

• code — every repo, both sides of each integration, searching for the concept and never only

the spot the artifact names;

• related tickets — on disk first; the tracker, read-only, for a specific doubt;
• designs the ticket references;
• other docs in the ticket's directory;
• branches and PRs the tickets link.
• **Future fit.** Does what the artifact delivers fit whoever builds on it next: a later ticket's

needs, the way the consumer's code already uses analogous things (names, shapes, errors, paging)?

• **Readiness.** A fresh session can act on the artifact without the ticket or any conversation;

no open question blocks the next phase; acceptance criteria are verifiable. Requirements say what, never how. A plan's steps are concrete enough to act on, ordered without broken intermediate states, and together cover every acceptance criterion.

Grounded bar: every finding names the document the mistake originates in and a citation verifiable blind — file path + lines + verbatim quote, ticket id + quoted text, or design frame id; zero findings is a valid outcome. The reviewer also reports, per source class, what it probed and what it could not reach — unreachable is unchecked, never skipped silently.

Done when the reviewer has returned its findings — possibly none — and its source coverage.

Challenge

A finding is a conclusion too: before any edit, try to disprove each one. Open its citation and confirm it exists as quoted **and proves the point** — related evidence is not proof — then hunt for what contradicts it: a written reason the reviewer missed, a code path elsewhere. Disproved → dropped, kept for the summary with why. Each survivor is:

• **proven** — ticket text or code settles both that it is a mistake and what the correct text is;
• **suspected** — everything else: not provable, more than one reasonable fix, or a fix that

changes what gets built beyond what the ticket states (most Future fit findings). A deviation with no written reason is suspected too — it may be a decision nobody recorded — unless the artifact contradicts itself on it (a requirement its acceptance criteria miss, a plan missing what its upstream requires) or the code proves its text wrong.

Done when every finding is dropped, proven or suspected.

Decide

One finding at a time, recommending a disposition with a one-line why, worded via `explain-in-simple-language` when available — t