[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M75A2GQ0RASJWXSAMC8CPXVR":3,"skill-same:01M75A2GQ0RASJWXSAMC8CPXVR":74},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":38,"commitSha":39,"skillDirectory":40,"forksCount":14,"repositoryHtmlUrl":41,"repositoryHomepageUrl":6,"ownerHtmlUrl":42,"ownerBlogUrl":43,"ownerDescription":44,"updatedAt":45,"install":46,"resources":59},"01M75A2GQ0RASJWXSAMC8CPXVR","rebuild-validation",null,"Use when validating that a structured artifact (spec, schema, contract, doc-set, runbook) is sufficient for an independent agent to reconstruct the underlying system from it alone. Triggers on \"blind rebuild test\", \"validate this spec\", \"is this documentation enough\", \"spec-driven regression\", \"contract test\", or when shipping any reverse-engineering \u002F spec \u002F schema work. Also covers refactor (the user edited R-\u002FS- entries and asks the agent to splice the diff into an existing codebase - \"按新 spec 改\", \"refactor to spec\", \"重写这个屎山\"). Drives a subagent that has NEVER seen the source artifact to read only the spec and rebuild against a graded machine-tickable two-key grading (functional-checklist.md + test-oracle.md), then surfaces diff-able weaknesses.","publieople\u002Fhermes-config-kit","publieople","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F90119344?v=4","01M759EPK59NZG525VKS4VRNC2","po","01M759EPM4EMVEY5JNV2549JQ1",0,"MIT","https:\u002F\u002Fgithub.com\u002Fpublieople\u002Fhermes-config-kit\u002Fblob\u002Fmaster\u002Fskills\u002F_archive\u002Fsoftware-development\u002Frebuild-validation\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: rebuild-validation\ndescription: Use when validating that a structured artifact (spec, schema, contract, doc-set, runbook) is sufficient for an independent agent to reconstruct the underlying system from it alone. Triggers on \"blind rebuild test\", \"validate this spec\", \"is this documentation enough\", \"spec-driven regression\", \"contract test\", or when shipping any reverse-engineering \u002F spec \u002F schema work. Also covers refactor (the user edited R-\u002FS- entries and asks the agent to splice the diff into an existing codebase - \"按新 spec 改\", \"refactor to spec\", \"重写这个屎山\"). Drives a subagent that has NEVER seen the source artifact to read only the spec and rebuild against a graded machine-tickable two-key grading (functional-checklist.md + test-oracle.md), then surfaces diff-able weaknesses.\nversion: 1.1.0\nauthor: Hermes Agent\nlicense: MIT\nmetadata:\n  hermes:\n    tags: [validation, spec, contract, subagent, regression]\n    related_skills: [test-driven-development, dispatching-parallel-agents, receiving-code-review]\n---\n\n# Rebuild Validation\n\nEmpirical validation that a structured artifact — a spec, a schema, a\ncontract, a documentation set — is **sufficient** for an independent agent\nto reconstruct the underlying thing from scratch.\n\nThe signal it produces is binary: PASS \u002F FAIL per checklist item. The\noutput is a bulleted list of items, each marked PASS or FAIL with a\none-line reason, plus specific patching suggestions for the author.\n\n## When to Use\n\n- You just wrote a spec \u002F contract \u002F schema and need to know if it's enough.\n- The artifact claims \"this is the source of truth for X\"; verify the claim.\n- A reverse-engineering pipeline (`A → spec`) needs a feedback loop.\n- Documentation accuracy: do these docs let a fresh agent complete the task?\n- An API client rebuild task: are these stub docs enough to implement against?\n- **Refactor scope:** the user edited `specs\u002F*.spec.md` (added\u002Fremoved\n  R- or S- entry) and asks you to splice the new behaviour into the\n  existing codebase without rebuilding it from scratch.\n\n**Don't use for**: unit tests, \"smoke tests\" of running code, or anything\nwhere the artifact isn't a static specification.\n\n## Two grading keys, not one\n\nA single `functional-checklist.md` answers \"does the rebuilt code ship\nthe right observable behaviour?\". That is not enough.\n\nEvery rebuild-grade spec SHOULD also include a `test-oracle.md` (or\nequivalent) — a per-symbol **white-box** grading key:\n\n```\n### `\u003Csymbol>`\n- input: \u003Cliteral, byte-exact>\n- expects: \u003Cliteral output> OR \u003Craises ExactException(message)>\n- pins: \u003Cone-line statement of WHICH invariant this pins>\n```\n\nWhy both:\n\n- **functional-checklist** = black box. \"Does the CLI exit 0 on\n  success, 2 on `ValueError`?\" — visible from outside the binary.\n- **test-oracle** = white box. \"Does `greet(\"   \")` raise\n  `ValueError` before or after `.strip()`?\" — pinned ordering the\n  checklist cannot distinguish. The order is what makes the function\n  correct; without oracle discipline, every rebuild gets it right *by\n  coincidence* and you only find out at runtime.\n\nWhat real roundtrips reveal: when both keys are run, the rebuild\ntypically passes 100% of checklist items (the easy grade) but fails\n5-15% of oracle items (the order-of-operations, full-width\npunctuation, error-before-format, dispatch-precedence class). The\noracle is what tells you the rebuild got the semantics right, not just\nthe behaviour. A green checklist with a red oracle is a **specific\nfailure** — list the exact oracle entry and the actual-vs-expected.\n\nThis skill consumes the oracle. The companion\n`reverse-engineer-spec` skill is responsible for *distilling* it: one\nor two fixtures per public surface from the original test suite (NOT\ncopying the whole test file). See `references\u002Foracle-distillation.md`\nfor the distillation method, and treat that file as the source of\ntruth for \"what goes into an oracle entry\".\n\n## Spec-edit → existing code (refactor)\n\nThis skill covers \"build a thing from spec\" (whole or scoped). The\ncompanion edit-an-existing-thing-per-spec path has different\ndiscipline and is captured here because the same grading keys apply:\n\n1. **Diff the spec.** Identify which `R-` \u002F `S-` \u002F oracle entries the\n   user added, removed, or edited. The user's edit is authoritative.\n2. **Classify each change** into: behaviour change (rewrite affected\n   symbol), conventions change (style \u002F imports \u002F error types),\n   inventory-only (count or wording shifted but no behaviour),\n   or **pure clarification** (codebase already satisfies it).\n3. **Snapshot the source.** `git worktree add ..\u002Fsnapshot` if the tree\n   is clean; otherwise refuse to run. With `side-by-side` strategy the\n   original directory *is* the rollback; no separate snapshot needed.\n4. **Spawn a leaf rewriter.** Constrain its scope to *only* the\n   affected symbols from step 2. It is forbidden to refactor\n   unrelated code, even ugly code. Patch, do not regenerate.\n5. **Run all three grading keys** (pytest + functional-checklist +\n   test-oracle). ALL THREE must be green.\n6. **Verify the diff matches the symbol list.** `git diff --stat`\n   between snapshot and rewriter output must touch only those files.\n   Anything else is a regression of trust.\n\nTwo outcomes worth distinguishing explicitly:\n\n- **All three green AND diff empty** → the edit was a *pure\n  clarification*. Passing outcome, not failure to edit. The user's\n  edit is now a documented intent, pinned by an oracle entry. Show\n  the new oracle entry as proof the clarification is exercised.\n- **All three green AND diff non-empty** → state the changed symbols\n  and confirm the spec edit is now in the code.\n\nThe failure of trust mode: rewriter touches code outside its scope.\nWhen `git diff` shows unrequested changes, **roll those back** and\ntighten the rewriter's scope. Otherwise the audit breaks: the user can\nno longer trust \"diff == edit\". Diff-vs-symbol-list is the audit\nbackbone of refactor; without it, refactor degrades into vibe-coding\nthat happens to also invoke pytest.\n\n## The Five-Step Pattern\n\n### 1. Write a graded checklist\n\n`functional-checklist.md` (or equivalent) is plain markdown with bullets:\n\n```\n- [ ] \u003Cconcrete check 1>\n- [ ] \u003Cconcrete check 2>\n```\n\nEach line MUST be machine-tickable: a concrete command, return value, or\nobservable outcome. \"Works\" \u002F \"looks right\" is not enough. Good:\n\n```\n- [ ] greet(\"Ada\", \"es\") returns \"Hola, Ada!\"\n- [ ] `pytest` exits 0\n- [ ] `greeter --help` writes usage to stdout, exit 0\n```\n\n**Pre-flight check before you even validate:** confirm the artifact\nitself is ready. The minimum survivable spec has (a) an entry-point\ndocument the validator will read first (`AGENTS.md` or equivalent) and\n(b) a `functional-checklist.md` with ≥5 `- [ ]` items. If either is\nmissing, **stop and tell the author** — running a validator against a\nstub spec produces a 0\u002F0 PASS that nobody can act on.\n\nSee `references\u002Fchecklist-template.md` for a starter.\n\n### 2. Pick a blind validator\n\nThe validator MUST have **zero access to the source artifact** that\nproduced the spec. Two ways to enforce:\n\n- Spawn a subagent in its own session; pass the spec path only.\n- Restart the current session so prior context is gone; feed the spec.\n\nThe validator MUST NOT use `git log`, web search, or any debugging aid\nthat could leak the original. If it can leak, the test is invalid.\n\n### 3. Let the validator pick its own scope\n\nFor large artifacts (>30 files or >5k LOC equivalent), the validator may\npick:\n\n- **whole**: rebuild everything from spec.\n- **single-module `\u003Cname>`**: rebuild one representative section. Pick\n  the section most users \u002F callers touch.\n- **single-file `\u003Cpath>`**: smallest scoped test.\n\nThe validator justifies its pick in one paragraph and proceeds. The\nauthor records the choice in `AGENTS.md`.\n\nWhy this matters: forcing whole-artifact validation on a 100k-LOC spec\nblows budget and produces false negatives. A well-chosen scoped PASS is\nmore useful than a global FAIL with token artifacts.\n\n### 4. Run the rebuild\n\nThe validator works the spec top-down: `AGENTS.md` → `architecture.md` →\nmodule specs → checklists. Conventions come last. After implementation,\nthe validator ticks every checklist item and reports PASS \u002F FAIL with\nreasons.\n\n### 5. Surface diff-able weaknesses\n\nAsk for **specific, actionable critique**, not narrative review. The\nprompt format that worked:\n\n> Critique the spec: which sections were clear, which were vague, where\n> you had to invent something not in the spec. **Name the heading** in\n> the spec. **Quote the missing text or rule** that would have made\n> rebuilding unambiguous.\n\nThe author converts each weakness into a `patch` against the spec (or\nagainst the producer skill). Re-run if cheap.\n\n**Two distinct signals, not one.** Always separate failures from debt:\n\n- **Failures** — checklist items the rebuild cannot tick. These mean\n  the spec is missing or wrong on a contract.\n- **Spec debt** — checklist items the rebuild ticked **but only by\n  inventing something not in the spec** (LICENSE body, dict-vs-if\n  branch, `print()` vs `sys.stdout.write`, etc.). These mean the spec\n  is insufficiently prescriptive. A green build with 4 inventions is a\n  weaker spec than a green build with 0 inventions, even though both\n  report \"20\u002F20 PASS\".\n\n**Always produce the spec-debt list, even on a fully green run.**\n\n## Strengths and Limits\n\n**Strengths**:\n- Quantifiable signal: `X \u002F N PASS, M with reasons`.\n- Catches contract drift, vocabulary mismatches, scope ambiguities, and\n  missing error-message literals that no static review catches.\n- Cheap: a 5-file codebase runs in ~30s of agent time.\n\n**Limits**:\n- Validator cost scales with spec size — scope must be chosen wisely.\n- Cannot grade non-functional areas (perf, security, aesthetics) without\n  explicit checklist items.\n- A passing rebuild ≠ a correct rebuild. The checklist must be\n  exhaustive; weak checklists pass weak specs.\n\n## Common Pitfalls\n\n1. **Leaky validator.** If the validator can see the original source\n   (via `find \u002Ftmp\u002F...` or browser history), the test is invalid.\n   Verify isolation by passing only the spec path.\n2. **Checklist that grades itself.** A checklist with \"looks reasonable\"\n   or \"is well-organized\" is unfalsifiable. Every item must be a concrete\n   check.\n3. **Forcing whole scope.** Letting validators bail to a smaller scope\n   when budget gets tight is correct, not failure. A scoped PASS with\n   reason beats a global FAIL with token noise.\n4. **Narrative review.** \"The spec was good but could be clearer\" is\n   not actionable. Demand heading + missing-text-level critique.\n5. **No re-run after fix.** Patch the spec, but skip re-validation when\n   it's cheap. Same weakness can hide for months otherwise.\n6. **Spec drift after the test.** If you patch the spec for unrelated\n   reasons, re-run; the build phase will hit drift.\n7. **Patching the rebuild until tests pass.** The validator's job is to\n   grade the spec, NOT to debug or rewrite the rebuild. A tweaked file\n   that now passes is a false green; the spec still has the gap. The\n   validator must output a graded checklist and stop. If you (the human\n   reading the report) are tempted to fix a failed item by editing the\n   rebuild, that is the bug. Roundtrip tests don't produce fixes; they\n   produce failure signals.\n8. **Treating metadata as contract.** LICENSE body text, README prose,\n   `pyproject.toml` `description` \u002F `author` fields — none are contract.\n   Let the rebuild invent them. A spec that tries to pin every\n   presentation field produces false-positive spec debt on every run.\n9. **Skipping the spec-debt list on a green run.** A green run with\n   inventions is a weaker spec than a green run with zero inventions.\n   Always list what the rebuild was forced to invent, even on PASS.\n10. **Accepting a green checklist when the oracle is red.** The\n    checklist is the easy grade; the oracle is the invariant check.\n    Always run both. A green checklist + red oracle is a specific\n    failure — list the oracle entry, not a vague PASS.\n11. **Refactor diffing beyond its scope.** When the rewriter outputs a\n    diff that touches more files than the symbol-list predicted, roll\n    the extra changes back and tighten the brief. Otherwise the audit\n    backbone (diff == edit) breaks and refactor degrades into\n    vibe-coding that happens to also pass pytest.\n\n## Verification Checklist\n\n- [ ] Pre-flight passed: entry-point doc exists, functional checklist has\n      ≥5 machine-tickable items.\n- [ ] Validator has no access to the source artifact.\n- [ ] Validator justified its scope choice if it picked \u003Cwhole>.\n- [ ] Report lists every checklist item with PASS \u002F FAIL \u002F reason.\n- [ ] Spec-debt list is present (not optional), and non-empty when the\n      validator invented anything **even on a fully green run**.\n- [ ] Critique names spec headings and quotes missing text, not narrative.\n- [ ] **No edits were made to the rebuild to mask failures.** Validator\n      output is the only output; reading the report, you must not feel\n      tempted to fix the rebuild.\n- [ ] Weaknesses are patched; if cheap, the rebuild was re-run.\n\n## One-Shot Recipes\n\n### Toy-repo roundtrip (~30s)\n\n```\n# 1. Pick a 5–10 file repo with tests\n# 2. Write functional-checklist.md with 10+ items\n# 3. Spawn subagent with only spec path; ask it to rebuild at \u002Ftmp\u002Frebuild-x\n# 4. Subagent runs the checklist, reports PASS \u002F FAIL\n```\n\n### Real-world module roundtrip (~5 min)\n\n```\n# 1. Pick a single high-coupling module (e.g. console.py for rich)\n# 2. Write specs\u002F\u003Cmodule>.spec.md with SHOULD \u002F MUST + Scenarios\n# 3. Subagent picks single-module scope; justifies\n# 4. Subagent rebuilds only the chosen surface and grades checklist\n```\n\n## References\n\n- `references\u002Fchecklist-template.md` — starter functional-checklist template.\n- `references\u002Froundtrip-prompt-template.md` — copy-paste subagent goal\n  template, with the whitelist + spec-debt pair that distinguishes a\n  graded rebuild from a vibe-coded one. Pair this with `references\u002Fchecklist-template.md`.\n- `references\u002Foracle-distillation.md` — how to distill a\n  `test-oracle.md` from an original test suite (one or two fixtures\n  per public surface, NOT a transcription). This is the producer side\n  that `reverse-engineer-spec` runs; this skill consumes its output.\n","# Rebuild Validation\n\nEmpirical validation that a structured artifact — a spec, a schema, a\ncontract, a documentation set — is **sufficient** for an independent agent\nto reconstruct the underlying thing from scratch.\n\nThe signal it produces is binary: PASS \u002F FAIL per checklist item. The\noutput is a bulleted list of items, each marked PASS or FAIL with a\none-line reason, plus specific patching suggestions for the author.\n\n## When to Use\n\n- You just wrote a spec \u002F contract \u002F schema and need to know if it's enough.\n- The artifact claims \"this is the source of truth for X\"; verify the claim.\n- A reverse-engineering pipeline (`A → spec`) needs a feedback loop.\n- Documentation accuracy: do these docs let a fresh agent complete the task?\n- An API client rebuild task: are these stub docs enough to implement against?\n- **Refactor scope:** the user edited `specs\u002F*.spec.md` (added\u002Fremoved\n  R- or S- entry) and asks you to splice the new behaviour into the\n  existing codebase without rebuilding it from scratch.\n\n**Don't use for**: unit tests, \"smoke tests\" of running code, or anything\nwhere the artifact isn't a static specification.\n\n## Two grading keys, not one\n\nA single `functional-checklist.md` answers \"does the rebuilt code ship\nthe right observable behaviour?\". That is not enough.\n\nEvery rebuild-grade spec SHOULD also include a `test-oracle.md` (or\nequivalent) — a per-symbol **white-box** grading key:\n\n```\n### `\u003Csymbol>`\n- input: \u003Cliteral, byte-exact>\n- expects: \u003Cliteral output> OR \u003Craises ExactException(message)>\n- pins: \u003Cone-line statement of WHICH invariant this pins>\n```\n\nWhy both:\n\n- **functional-checklist** = black box. \"Does the CLI exit 0 on\n  success, 2 on `ValueError`?\" — visible from outside the binary.\n- **test-oracle** = white box. \"Does `greet(\"   \")` raise\n  `ValueError` before or after `.strip()`?\" — pinned ordering the\n  checklist cannot distinguish. The order is what makes the function\n  correct; without oracle discipline, every rebuild gets it right *by\n  coincidence* and you only find out at runtime.\n\nWhat real roundtrips reveal: when both keys are run, the rebuild\ntypically passes 100% of checklist items (the easy grade) but fails\n5-15% of oracle items (the order-of-operations, full-width\npunctuation, error-before-format, dispatch-precedence class). The\noracle is what tells you the rebuild got the semantics right, not just\nthe behaviour. A green checklist with a red oracle is a **specific\nfailure** — list the exact oracle entry and the actual-vs-expected.\n\nThis skill consumes the oracle. The companion\n`reverse-engineer-spec` skill is responsible for *distilling* it: one\nor two fixtures per public surface from the original test suite (NOT\ncopying the whole test file). See `references\u002Foracle-distillation.md`\nfor the distillation method, and treat that file as the source of\ntruth for \"what goes into an oracle entry\".\n\n## Spec-edit → existing code (refactor)\n\nThis skill covers \"build a thing from spec\" (whole or scoped). The\ncompanion edit-an-existing-thing-per-spec path has different\ndiscipline and is captured here because the same grading keys apply:\n\n1. **Diff the spec.** Identify which `R-` \u002F `S-` \u002F oracle entries the\n   user added, removed, or edited. The user's edit is authoritative.\n2. **Classify each change** into: behaviour change (rewrite affected\n   symbol), conventions change (style \u002F imports \u002F error types),\n   inventory-only (count or wording shifted but no behaviour),\n   or **pure clarification** (codebase already satisfies it).\n3. **Snapshot the source.** `git worktree add ..\u002Fsnapshot` if the tree\n   is clean; otherwise refuse to run. With `side-by-side` strategy the\n   original directory *is* the rollback; no separate snapshot needed.\n4. **Spawn a leaf rewriter.** Constrain its scope to *only* the\n   affected symbols from step 2. It is forbidden to refactor\n   unrelated code, even ugly code. Patch, do not regenerate.\n5. **Run all three grading keys** (pytest + functional-checklist +\n   test-oracle). ALL THREE must be green.\n6. **Verify the diff matches the symbol list.** `git diff --stat`\n   between snapshot and rewriter output must touch only those files.\n   Anything else is a regression of trust.\n\nTwo outcomes worth distinguishing explicitly:\n\n- **All three green AND diff empty** → the edit was a *pure\n  clarification*. Passing outcome, not failure to edit. The user's\n  edit is now a documented intent, pinned by an oracle entry. Show\n  the new oracle entry as proof the clarification is exercised.\n- **All three green AND diff non-empty** → state the changed symbols\n  and confirm the spec edit is now in the code.\n\nThe failure of trust mode: rewriter touches code outside its scope.\nWhen `git diff` shows unrequested changes, **roll those back** and\ntighten the rewriter's scope. Otherwise the audit breaks: the user can\nno longer trust \"diff == edit\". Diff-vs-symbol-list is the audit\nbackbone of refactor; without it, refactor degrades into vibe-coding\nthat happens to also invoke pytest.\n\n## The Five-Step Pattern\n\n### 1. Write a graded checklist\n\n`functional-checklist.md` (or equivalent) is plain markdown with bullets:\n\n```\n- [ ] \u003Cconcrete check 1>\n- [ ] \u003Cconcrete check 2>\n```\n\nEach line MUST be machine-tickable: a concrete command, return value, or\nobservable outcome. \"Works\" \u002F \"looks right\" is not enough. Good:\n\n```\n- [ ] greet(\"Ada\", \"es\") returns \"Hola, Ada!\"\n- [ ] `pytest` exits 0\n- [ ] `greeter --help` writes usage to stdout, exit 0\n```\n\n**Pre-flight check before you even validate:** confirm the artifact\nitself is ready. The minimum survivable spec has (a) an entry-point\ndocument the validator will read first (`AGENTS.md` or equivalent) and\n(b) a `functional-checklist.md` with ≥5 `- [ ]` items. If either is\nmissing, **stop and tell the author** — running a validator against a\nstub spec produces a 0\u002F0 PASS that nobody can act on.\n\nSee `references\u002Fchecklist-template.md` for a starter.\n\n### 2. Pick a blind validator\n\nThe validator MUST have **zero access to the source artifact** that\nproduced the spec. Two ways to enforce:\n\n- Spawn a subagent in its own session; pass the spec path only.\n- Restart the current session so prior context is gone; feed the spec.\n\nThe validator MUST NOT use `git log`, web search, or any debugging aid\nthat could leak the original. If it can leak, the test is invalid.\n\n### 3. Let the validator pick its own scope\n\nFor large artifacts (>30 files or >5k LOC equivalent), the validator may\npick:\n\n- **whole**: rebuild everything from spec.\n- **single-module `\u003Cname>`**: rebuild one representative section. Pick\n  the section most users \u002F callers touch.\n- **single-file `\u003Cpath>`**: smallest scoped test.\n\nThe validator justifies its pick in one paragraph and proceeds. The\nauthor records the choice in `AGENTS.md`.\n\nWhy this matters: forcing whole-artifact validation on a 100k-LOC spec\nblows budget and produces false negatives. A well-chosen scoped PASS is\nmore useful than a global FAIL with token artifacts.\n\n### 4. Run the rebuild\n\nThe validator works the spec top-down: `AGENTS.md` → `architecture.md` →\nmodule specs → checklists. Conventions come last. After implementation,\nthe validator ticks every checklist item and reports PASS \u002F FAIL with\nreasons.\n\n### 5. Surface diff-able weaknesses\n\nAsk for **specific, actionable critique**, not narrative review. The\nprompt format that worked:\n\n> Critique the spec: which sections were clear, which were vague, where\n> you had to invent something not in the spec. **Name the heading** in\n> the spec. **Quote the missing text or rule** that would have made\n> rebuilding unambiguous.\n\nThe author converts each weakness into a `patch` against the spec (or\nagainst the producer skill). Re-run if cheap.\n\n**Two distinct signals, not one.** Always separate failures from debt:\n\n- **Failures** — checklist items the rebuild cannot tick. These mean\n  the spec is missing or wrong on a contract.\n- **Spec debt** — checklist items the rebuild ticked **but only by\n  inventing something not in the spec** (LICENSE body, dict-vs-if\n  branch, `print()` vs `sys.stdout.write`, etc.). These mean the spec\n  is insufficiently prescriptive. A green build with 4 inventions is a\n  weaker spec than a green build with 0 inventions, even though both\n  report \"20\u002F20 PASS\".\n\n**Always produce the spec-debt list, even on a fully green run.**\n\n## Strengths and Limits\n\n**Strengths**:\n- Quantifiable signal: `X \u002F N PASS, M with reasons`.\n- Catches contract drift, vocabulary mismatches, scope ambiguities, and\n  missing error-message literals that no static review catches.\n- Cheap: a 5-file codebase runs in ~30s of agent time.\n\n**Limits**:\n- Validator cost scales with spec size — scope must be chosen wisely.\n- Cannot grade non-functional areas (perf, security, aesthetics) without\n  explicit checklist items.\n- A passing rebuild ≠ a correct rebuild. The checklist must be\n  exhaustive; weak checklists pass weak specs.\n\n## Common Pitfalls\n\n1. **Leaky validator.** If the validator can see the original source\n   (via `find \u002Ftmp\u002F...` or browser history), the test is invalid.\n   Verify isolation by passing only the spec path.\n2. **Checklist that grades itself.** A checklist with \"looks reasonable\"\n   or \"is well-organized\" is unfalsifiable. Every item must be a concrete\n   check.\n3. **Forcing whole scope.** Letting validators bail to a smaller scope\n   when budget gets tight is correct, not failure. A scoped PASS with\n   reason beats a global FAIL with token noise.\n4. **Narrative review.** \"The spec was good but could be clearer\" is\n   not actionable. Demand heading + missing-text-level critique.\n5. **No re-run after fix.** Patch the spec, but skip re-validation when\n   it's cheap. Same weakness can hide for months otherwise.\n6. **Spec drift after the test.** If you patch the spec for unrelated\n   reasons, re-run; the build phase will hit drift.\n7. **Patching the rebuild until tests pass.** The validator's job is to\n   grade the spec, NOT to debug or rewrite the rebuild. A tweaked file\n   that now passes is a false green; the spec still has the gap. The\n   validator must output a graded checklist and stop. If you (the human\n   reading the report) are tempted to fix a failed item by editing the\n   rebuild, that is the bug. Roundtrip tests don't produce fixes; they\n   produce failure signals.\n8. **Treating metadata as contract.** LICENSE body text, README prose,\n   `pyproject.toml` `description` \u002F `author` fields — none are contract.\n   Let the rebuild invent them. A spec that tries to pin every\n   presentation field produces false-positive spec debt on every run.\n9. **Skipping the spec-debt list on a green run.** A green run with\n   inventions is a weaker spec than a green run with zero inventions.\n   Always list what the rebuild was forced to invent, even on PASS.\n10. **Accepting a green checklist when the oracle is red.** The\n    checklist is the easy grade; the oracle is the invariant check.\n    Always run both. A green checklist + red oracle is a specific\n    failure — list the oracle entry, not a vague PASS.\n11. **Refactor diffing beyond its scope.** When the rewriter outputs a\n    diff that touches more files than the symbol-list predicted, roll\n    the extra changes back and tighten the brief. Otherwise the audit\n    backbone (diff == edit) breaks and refactor degrades into\n    vibe-coding that happens to also pass pytest.\n\n## Verification Checklist\n\n- [ ] Pre-flight passed: entry-point doc exists, functional checklist has\n      ≥5 machine-tickable items.\n- [ ] Validator has no access to the source artifact.\n- [ ] Validator justified its scope choice if it picked \u003Cwhole>.\n- [ ] Report lists every checklist item with PASS \u002F FAIL \u002F reason.\n- [ ] Spec-debt list is present (not optional), and non-empty when the\n      validator invented anything **even on a fully green run**.\n- [ ] Critique names spec headings and quotes missing text, not narrative.\n- [ ] **No edits were made to the rebuild to mask failures.** Validator\n      output is the only output; reading the report, you must not feel\n      tempted to fix the rebuild.\n- [ ] Weaknesses are patched; if cheap, the rebuild was re-run.\n\n## One-Shot Recipes\n\n### Toy-repo roundtrip (~30s)\n\n```\n# 1. Pick a 5–10 file repo with tests\n# 2. Write functional-checklist.md with 10+ items\n# 3. Spawn subagent with only spec path; ask it to rebuild at \u002Ftmp\u002Frebuild-x\n# 4. Subagent runs the checklist, reports PASS \u002F FAIL\n```\n\n### Real-world module roundtrip (~5 min)\n\n```\n# 1. Pick a single high-coupling module (e.g. console.py for rich)\n# 2. Write specs\u002F\u003Cmodule>.spec.md with SHOULD \u002F MUST + Scenarios\n# 3. Subagent picks single-module scope; justifies\n# 4. Subagent rebuilds only the chosen surface and grades checklist\n```\n\n## References\n\n- `references\u002Fchecklist-template.md` — starter functional-checklist template.\n- `references\u002Froundtrip-prompt-template.md` — copy-paste subagent goal\n  template, with the whitelist + spec-debt pair that distinguishes a\n  graded rebuild from a vibe-coded one. Pair this with `references\u002Fchecklist-template.md`.\n- `references\u002Foracle-distillation.md` — how to distill a\n  `test-oracle.md` from an original test suite (one or two fixtures\n  per public surface, NOT a transcription). This is the producer side\n  that `reverse-engineer-spec` runs; this skill consumes its output.\n",{"name":5,"author":24,"license":15,"version":25,"metadata":26,"description":7},"Hermes Agent","1.1.0",{"hermes":27},{"tags":28,"related_skills":34},[29,30,31,32,33],"validation","spec","contract","subagent","regression",[35,36,37],"test-driven-development","dispatching-parallel-agents","receiving-code-review","master","2cd115c9a59092e1d0cf18805c164d7a57a7f123","skills\u002F_archive\u002Fsoftware-development\u002Frebuild-validation","https:\u002F\u002Fgithub.com\u002Fpublieople\u002Fhermes-config-kit","https:\u002F\u002Fgithub.com\u002Fpublieople","https:\u002F\u002Fwww.for-people.cn","Truly provide effective services for the real people","2026-10-11 09:10:19",{"source":8,"skillName":5,"commands":47,"prompt":57,"zipAvailable":58},[48,51,54],{"tool":49,"command":50},"npx","npx skills add publieople\u002Fhermes-config-kit --skill rebuild-validation",{"tool":52,"command":53},"bunx","bunx skills add publieople\u002Fhermes-config-kit --skill rebuild-validation",{"tool":55,"command":56},"pnpm","pnpm dlx skills add publieople\u002Fhermes-config-kit --skill rebuild-validation","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fpublieople\u002Fhermes-config-kit\u002Fblob\u002Fmaster\u002Fskills\u002F_archive\u002Fsoftware-development\u002Frebuild-validation\u002FSKILL.md",true,[60,66,70],{"path":61,"resourceType":62,"resourceTypeDesc":63,"sizeBytes":64,"sourceHtmlUrl":65},"references\u002Fchecklist-template.md","REFERENCE","参考文档",1580,"https:\u002F\u002Fgithub.com\u002Fpublieople\u002Fhermes-config-kit\u002Fblob\u002Fmaster\u002Fskills\u002F_archive\u002Fsoftware-development\u002Frebuild-validation\u002Freferences\u002Fchecklist-template.md",{"path":67,"resourceType":62,"resourceTypeDesc":63,"sizeBytes":68,"sourceHtmlUrl":69},"references\u002Foracle-distillation.md",6340,"https:\u002F\u002Fgithub.com\u002Fpublieople\u002Fhermes-config-kit\u002Fblob\u002Fmaster\u002Fskills\u002F_archive\u002Fsoftware-development\u002Frebuild-validation\u002Freferences\u002Foracle-distillation.md",{"path":71,"resourceType":62,"resourceTypeDesc":63,"sizeBytes":72,"sourceHtmlUrl":73},"references\u002Froundtrip-prompt-template.md",5676,"https:\u002F\u002Fgithub.com\u002Fpublieople\u002Fhermes-config-kit\u002Fblob\u002Fmaster\u002Fskills\u002F_archive\u002Fsoftware-development\u002Frebuild-validation\u002Freferences\u002Froundtrip-prompt-template.md",[75,81,88,95,102,109],{"skillNo":76,"name":35,"nameZh":6,"description":77,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":78,"categories":79,"keywords":80,"publishedAt":19},"01M75A845WYE5R2AFVSS7YHBJV","TDD: enforce RED-GREEN-REFACTOR, tests before code.","https:\u002F\u002Fgithub.com\u002Fpublieople\u002Fhermes-config-kit\u002Fblob\u002Fmaster\u002Fskills\u002Fsoftware-development\u002Ftest-driven-development\u002FSKILL.md",[],[],{"skillNo":82,"name":83,"nameZh":6,"description":84,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":85,"categories":86,"keywords":87,"publishedAt":19},"01M75A7QKQZD6YVEJ55KYNBHM1","systematic-debugging","4-phase root cause debugging: understand bugs before fixing.","https:\u002F\u002Fgithub.com\u002Fpublieople\u002Fhermes-config-kit\u002Fblob\u002Fmaster\u002Fskills\u002Fsoftware-development\u002Fsystematic-debugging\u002FSKILL.md",[],[],{"skillNo":89,"name":90,"nameZh":6,"description":91,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":92,"categories":93,"keywords":94,"publishedAt":19},"01M75A7NCY8TJN7BVDV7GKQJNE","simplify-code","Parallel 4-agent cleanup of recent code changes.","https:\u002F\u002Fgithub.com\u002Fpublieople\u002Fhermes-config-kit\u002Fblob\u002Fmaster\u002Fskills\u002Fsoftware-development\u002Fsimplify-code\u002FSKILL.md",[],[],{"skillNo":96,"name":97,"nameZh":6,"description":98,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":99,"categories":100,"keywords":101,"publishedAt":19},"01M75A7JW7JHDNNKYGFQDP4E2M","inspecting-hermes-desktop-dom","Read the live Hermes desktop DOM\u002FCSS over CDP.","https:\u002F\u002Fgithub.com\u002Fpublieople\u002Fhermes-config-kit\u002Fblob\u002Fmaster\u002Fskills\u002Fsoftware-development\u002Finspecting-hermes-desktop-dom\u002FSKILL.md",[],[],{"skillNo":103,"name":104,"nameZh":6,"description":105,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":106,"categories":107,"keywords":108,"publishedAt":19},"01M75A7EP72GHSVHW337XD75CR","hermes-agent-skill-authoring","Author in-repo SKILL.md files: frontmatter and structure.","https:\u002F\u002Fgithub.com\u002Fpublieople\u002Fhermes-config-kit\u002Fblob\u002Fmaster\u002Fskills\u002Fsoftware-development\u002Fhermes-agent-skill-authoring\u002FSKILL.md",[],[],{"skillNo":110,"name":111,"nameZh":6,"description":112,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":113,"categories":114,"keywords":115,"publishedAt":19},"01M75A7BGWRT0453313CJKP4SC","github","GitHub via gh CLI: PRs, issues, reviews, repos, auth.","https:\u002F\u002Fgithub.com\u002Fpublieople\u002Fhermes-config-kit\u002Fblob\u002Fmaster\u002Fskills\u002Fsoftware-development\u002Fgithub\u002FSKILL.md",[],[]]