docs(board): add plain-language summary columns to the gap board - #496
Merged
Conversation
Two columns after `Gap`: "In plain terms" (what is wrong, in one jargon-free sentence) and "What it fixes" (what closing it buys). The `Gap` column is written for whoever implements the row and is unreadable for anyone deciding whether to fund it; these two are the funding view. Safe against the guards because both board parsers are HEADER-DRIVEN, not positional: 08-validate-tracking and board/debt-economics locate Status by header name with a last-column fallback, and both use the same `splitRow` that respects `\|` escapes. The migration therefore had one hard requirement -- every row ends with the same cell count -- and the script enforces it, throwing on any row that does not arrive with exactly 7 cells rather than half-migrating the board. Verified after: 685/685 rows carry 9 cells in both languages, and the debt-economics parser still resolves GT-677 to `status: PENDING`. Maintained for OPEN rows only; a closed row carries an em dash. That is deliberate: a DONE row's story is its closure-evidence record, and back-filling 654 summaries from titles would manufacture text nobody measured. The script refuses to leave an open row blank, so a new row cannot slip through empty. All 31 open rows carry both cells in EN and ES -- 19 PENDING, 2 IN-PROGRESS, 10 DEFERRED -- and a legend states that the columns are a VIEW and that the catalog wins wherever they disagree. Guards: 08-validate-tracking OK (685 gaps, 661/661 EN/ES sections, 31/31 open rows with criteria and debt economics), 04-check-bilingual-parity OK, 01-validate-docs OK (1505 files), 49-validate-gap-id-allocation OK, 46-validate-derived-artifact-order current and at a fixed point. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
📊 Bilingual Coverage ImpactPR Changes
Repository Coverage
✅ Good: All EN changes have ES counterparts. Generated by GitHub Actions |
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.
Two reader-facing columns after
Gap: In plain terms (what is wrong, in one jargon-free sentence) and What it fixes (what closing it buys). Documentation only — no source change.The
Gapcolumn is written for whoever implements the row and is unreadable for anyone deciding whether to fund it. These two columns are the funding view.Why this is safe against the guards
Both board parsers are header-driven, not positional:
08-validate-trackingandboard/debt-economicslocateStatusby header name with a last-column fallback, and both use the samesplitRowthat respects\|escapes. The migration therefore had exactly one hard requirement — every row must end with the same cell count — and the script enforces it, throwing on any row that does not arrive with exactly 7 cells rather than half-migrating the board.Verified after the migration: 685/685 rows carry 9 cells in both languages, and the debt-economics parser still resolves
GT-677tostatus: PENDING.Maintenance rule, stated in the board itself
Maintained for open rows only; a closed row carries an em dash. A
DONErow's story is its closure-evidence record, and back-filling 654 summaries from titles would manufacture text nobody measured — which is the defect this board exists to catch. The migration script refuses to leave an open row blank, so a new row cannot slip through empty.All 31 open rows carry both cells in EN and ES: 19 pending, 2 in progress, 10 deferred. A legend states that the columns are a VIEW and that the catalog wins wherever they disagree.
Guards run locally
08-validate-tracking(685 gaps, 661/661 EN/ES catalog sections, 31/31 open rows with criteria and debt economics) ·04-check-bilingual-parity·01-validate-docs(1505 files) ·49-validate-gap-id-allocation·46-validate-derived-artifact-ordercurrent and at a fixed point.🤖 Generated with Claude Code