design-retro-publishability-gate

name	design-retro-publishability-gate
description	Final whole-docset publishability gate for design-retro / adversarial-doc swarm workflows. Use as the LAST stage of any design-retro, solutions-hardening, /innov, pr-retro, or code-quality-swarm run, after all writer/verifier lanes finish and before the PR description claims the docset is "ready" or "publishable". Catches cross-document contradictions, present-tense staleness vs current HEAD, leaked machine paths/tokens, unmarked superseded docs, false-green copyable commands, and git diff --check hygiene issues that per-finding adversarial review structurally cannot see.
type	skill
scope	repo
owner	$USER
version	1.0.0
triggers	["publishability gate","final design-retro check","is this docset publishable","whole-docset review before publishing","synthesize-report final check"]
allowed-tools	["Bash","Read","Grep"]
context	["Root cause: PR https://github.com/$GITHUB_REPOSITORY/pull/8191 ran ~180 adversarial agents across design-retro, solutions-hardening, innov, pr-retro, and code-quality lanes, validating/refuting candidate FINDINGS, but never re-read the assembled markdown as a single publishable artifact. A cold review found six defect classes still present in already-'confirmed' docs. Full writeup: docs/design-retro-2026-06-adversarial-gaps.md (this repo). This SKILL.md is the fix (bead rev-qj6qb).","This mirrors and operationalizes ~/.claude/skills/swarm/SKILL.md rule 11 ('Publishability gate') for THIS repo. If that user-scope rule's wording changes, re-sync the checklist below rather than let them drift.","This is a planning/process gate, not application code. Nothing here does keyword/regex SEMANTIC judgment (contradiction detection, staleness detection, supersession detection) in a script — those three items are LLM-judgment checklist items by design, per this repo's ZFC principle (CLAUDE.md 'Zero-Framework Cognition'). The companion script only does mechanical, non-semantic checks: secret-shape pattern matching, shell syntax validation, and git's own diff --check."]

Design-Retro Publishability Gate

When to use this skill

Run this gate exactly once, as the final stage, in any workflow that:

• fans out multiple writer agents across sibling docs (design-retro, solutions-hardening, /innov, pr-retro, code-quality swarms), and
• uses single-file write locks per agent (so no single agent ever held the whole docset in context), and
• is about to have its PR description say the docset is "ready", "publishable", or "final".

Do not substitute this for per-finding adversarial verification (evidence/severity/design lenses). This gate assumes those already ran. It exists because per-finding verification structurally cannot see problems that only exist at the whole-docset level (contradictions between docs, stale corrections, leaked paths, unmarked superseded plans).

Why per-finding review misses this (do not re-derive this — it is proven)

From docs/design-retro-2026-06-adversarial-gaps.md §2, six structural reasons, condensed:

1. Verifiers ran on candidate findings before doc writers wrote the rendered markdown — nothing ever re-read the shipped prose.
2. Single-file write locks (needed for parallel-safety) guaranteed no agent ever held two docs in context, so cross-doc contradictions were invisible by construction.
3. Corrections landed only in the doc that produced them; the top-level report (written earlier, by a different agent) was never reopened.
4. No freshness re-baseline: docs were checked against one HEAD; later commits changed ground truth; present-tense claims went stale silently.
5. Policy compliance (ZFC / ZFC-leveling / credential-discipline / regex bans) was never a review lens — a recommendation can be evidentially true and still be forbidden.
6. The one lane structurally positioned to catch all of this (synthesize-report) failed on provider overload in the original PR #8191 run and was finished by hand, without gate checks.

The checklist (run in this order)

Run the automated subset first (cheap, deterministic); only spend LLM judgment on the items that need it.

Automated (companion script — run first)

scripts/check_design_retro_publishability.sh <doc1.md> [doc2.md ...]

#	Check	What it does	Exit signal
3	Redaction sweep	Greps every doc for machine-path and token-shape patterns (/Users/<name>, //, , , AWS/ key shapes). Fixed pattern list, not a semantic classifier.