README: restructure pair-first — two journeys, four commands#20
Merged
Conversation
…uses not-repairable DISCOVERY.md previously had no way to say 'this can't be repaired because it was never built' — only blocker severity. Now: - discover emits a top-of-file Repairability verdict (repairable | partially-runnable | not-repairable) and splits fixable blockers from never-built gaps; gaps never become DoD checkboxes - repair gains a second refusal: it stops on not-repairable, keeps gaps out of scope on partially-runnable, and treats a missing verdict field (pre-existing DISCOVERY.md files) as repairable - README + OVERVIEW updated to match Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Four commands read as four choices; they're not. Lead with the two journeys (discover→repair, audit→audit-repair), each plan → you approve → execute: - 'Which to reach for' becomes 'Two journeys, four commands' — a two-row journey table (guard as a standing line, not a row) - new callout: don't memorize the order — every skill routes you to the right phase (repair offers discover; audit-repair refuses without a ratified audit) - mermaid finally shows the audit→audit-repair leg (it dead-ended at the report, predating v0.4.0) - command table split into the two journey groups - intro bullets name their command pairs; FAQ rows catch up to audit-repair Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
With
audit-repairshipped in v0.4.0, the README presents four commands, and they read as four choices the user must get right. They're not — they're the steps of two journeys with the same shape: plan → you approve → execute. This PR restructures the README so the journey is the unit you pick, and the commands are just its steps. Presentation only — no skill, manifest, or behavior changes.What changed
## 🧭 Which to reach for→## 🧭 Two journeys, four commands. The four-row situation table becomes a two-row journey table — make it run (discover→ approve →repair) and assess it, optionally fix it (audit→ your call →audit-repair). The guard moves from a table row to a standing sentence (it isn't a choice).repairwith no plan stops and offersdiscover;discovernames the next command;audit-repairrefuses without a ratified audit. This was already true in the skills; the README never said it.CODEBASE_AUDIT.md(drawn pre-audit-repair). It now shows the optional ratify →audit-repair→ findings-fixed leg, dotted to signal opt-in.audit-repair.Stacking
Based on #19 (
feat/discover-repairability-verdict), because both touch the command-table rows. Merge #19 first — GitHub will retarget this PR tomainautomatically. Review here shows only the restructure.Context
Follows the "don't merge discover+repair" decision: the four-skill architecture stays exactly as is (the ratify gate is load-bearing and Plan-Mode-enforced); the confusion was in the telling, so the fix is in the README.
🤖 Generated with Claude Code