Repository navigation
docs: describe shipped behavior, define reviewer enums, guard locale parity (2.1.2) - #62
Merged
Merged
Conversation
The original implementation plans lived in five translated copies under docs/<locale>/plans/ (about 20k lines) and each opened with an imperative to execute it. - Keep the English copy at docs/archive/plans/. - Add a banner to each plan: historical record, do not execute, current behavior is in docs/en/design.md. - Remove the zh-TW, zh-CN, ja and ko copies. - The self-audit ignore glob (docs/*/plans/**) still covers the new path; only its comment changes. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
design.md called itself the SSOT but described behavior the code does not have. Fix the doc, not the code, in all five locales: - Remove the API retry/backoff row; no retry exists. - Remove report.issue_label from the audit.yml example; nothing reads it. The label is the issue_label workflow input. - "All reviewers fail" now says what happens: the run completes and the issue carries an incomplete-run warning. - Section 7 no longer promises chunking, summarizing, downscaling or a "not inspected" list. oversizedText is a flag in the inventory. - Triggers: the reusable workflow is workflow_call only; the caller owns the trigger and there are no scope inputs. - Drop machine-specific paths and the local directory name. - Section 11 is "out of scope", without the second meaning of "v2". - Add reviewers.<name>.paths and reviewers.<name>.rubric to section 5, with one line per key. - Define stale_a / stale_b and list every allowed enum value in section 4. - Point at docs/archive/plans/ instead of docs/<locale>/plans/. Fenced code blocks in the four translated files are now byte-identical to the English ones, as CLAUDE.md requires. Explanations that lived in translated block comments moved to prose below each block. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The reviewer prompts left a smaller model guessing in several places. The JSON field names and allowed values are unchanged; src/findings.ts and src/synthesis.ts still accept the same output. Shared reviewer prompt: - "Work only within your target files" read as a ban on opening the other side of a comparison. It now says: report only on target files, read any other repo file as evidence. - Enum values were written as one pipe-joined string inside the JSON example. The example now shows one concrete value per field, and a table per field lists the allowed values with the criterion for each (category, severity, confidence, ssot_direction). - stale_a means `file` is the outdated side; stale_b means the first entry of `related` is. `related` is defined. - Each inventory field is defined, including what to do when oversizedText is true. - The turn budget no longer quotes a default that max_turns can change. Rubrics: every "what to look for" bullet names the category to use. docs_staleness and convention say which field carries the direction and the cited rule. Synthesis prompt gets the same enum treatment. The recorded contract sample marked a lagging translation as stale_b although the translation was `file`; it is stale_a under the definition. test/locale-parity.test.ts checks that reviewers/en and reviewers/zh-TW hold the same files with the same line structure and JSON contract, that the contract examples pass the pipeline validators, and that docs code blocks are byte-identical across the five locales. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
- Add a numbered change and release procedure taken from what the repo does: PR against main, build + test (same as CI), plugin version bump, squash merge, Dependabot auto-merge, version tag + release, rolling v2. - Say when v2 moves (a change to what @v2 callers run) and give the non-interactive command with the tag's existing message. - Move the two-file plugin version rule out of a long sentence into its own list. - Name the English base files of the 5-locale docs. - Add the reviewers/en <-> reviewers/zh-TW sync rule and point both sync rules at test/locale-parity.test.ts. - docs/archive/plans/ and docs/superpowers/ are historical records; docs/en/design.md is the current truth. - Drop the local directory name, which is not true of every checkout. - The finalize helpers live in src/finalize.ts, not src/report.ts. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
All README, overview and why-reusable-workflow changes are mirrored in the five locales. - README and skill: document the --keep-work flag of local-audit.sh. - Skill: the required --out step is its own numbered step instead of a clause inside a paragraph; say when not to use the skill and which script lines show progress. - README and overview reviewer tables: code_hygiene and visual_icon now list what the rubrics check, not "commented-out blocks" or "branding". - README link text shows the real path (docs/en/..., docs/<locale>/...). - README names the config key report.min_severity, as design.md does. - why-reusable-workflow: checkout@v7 and @v2 in the examples, matching the README; drop "as of v2.1". - rubric_lang descriptions say "en or zh-TW"; any other value fails. - SECURITY: matrix-job isolation is true only for the reusable workflow; state the tool allowlist that holds for all three entry points. - CONTRIBUTING: docs/superpowers/ is not English-only; add the reviewer locale sync rule. - self-audit comment no longer claims coverage of reviewers/<locale>/. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The reviewer prompts and the skill text changed. Both version fields move together: plugin.json and marketplace.json. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Review follow-up. test/locale-parity.test.ts: - Parse each enum table of the reviewer prompt on its own and require exactly the values of the matching constant in src/types.ts, so a missing row or an extra row fails. - Require every category a rubric names to be in FINDING_CATEGORIES. - Compare the backticked tokens of each line between en and zh-TW, so a sentence that names a different value fails. - Derive the docs file list from docs/en and require each locale directory to hold the same set (plus README.md). - List only .md files, share one fence helper, and throw on an unterminated fence. - One test case per file or locale (it.each) instead of loops. Prompts and docs: - zh-TW reviewer and synthesis prompts: two lines now name the same code tokens as the English lines. - Reviewer prompt: the inventory entries sit under the `files` key. - design.md (5 locales): the order of `related` is meaningful only in findings/<reviewer>.json; Consolidate sorts it. Drop "leaves a log entry" for an empty inventory; nothing logs it. Co-Authored-By: Claude Fable 5.2 <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
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.
What
Documentation and reviewer-prompt health check. The action's code is unchanged; the only code added is a test.
docs/*/design.md(5 locales): describes shipped behavior only. Removed retry with backoff, thereport.issue_labelconfig key, perceptual hashing and other claims the code does not implement; completed the config schema (reviewers.<name>.paths,.rubric); code blocks are now byte-identical across locales.reviewers/enandreviewers/zh-TW: every enum value is defined in a table (category,severity,confidence,ssot_directionincl.stale_a/stale_b),relatedis defined, each rubric bullet names its category, and the "target files only" rule no longer reads as a ban on reading other files. The JSON contract is unchanged: no field renamed, added or removed.test/locale-parity.test.ts(new): reviewers en/zh-TW stay in structural and code-token parity, enum tables equal the constants insrc/types.ts, rubric categories are valid, prompt examples pass the validators, docs code blocks and file sets match across the five locales.docs/<locale>/plans/: 20 locale copies of archived plans collapsed into one copy atdocs/archive/plans/with a "historical record, do not execute" banner (about 15k lines removed).CLAUDE.md: adds the change and release procedure and the locale sync rules.SKILL.md,SECURITY.md,CONTRIBUTING.md, and descriptions/comments inaction.ymland.github/.plugin.json,marketplace.json), because shipped reviewer prompts changed.Why
Two independent audits (a deep review and a cold-reader pass) found docs claiming behavior the code lacks, and reviewer prompts with undefined enum values that a small model would have to guess. The goal is docs and prompts that a small model can follow as well as a strong one.
Checklist
npm ci && npm run build && npm testpass locally: 29 files, 208 tests.DS_Storedoes not.github/andaction.ymlchanges are comments and descriptions onlystatus: okwith output that passed the validators. Finding counts: 0 on this branch; the last run on main (2026-11-09) had 2 low-severitycode_hygienefindings in files this PR does not touch. One run does not show whether that is model variance or lower recall from the new prompt wording.After merge
Tag
v2.1.2and publish a release. The rollingv2tag is not moved in this step: that waits for the owner, given the open recall question above.Open items for the owner (no action needed to merge)
src/config.tsstill parses the unusedreport.issue_labelkey, andsrc/prompt-bundle.ts:30still emits the heading "review ONLY these"; code was out of scope, the docs and prompts now explain both.claude-opus-4-8appears as the default model in 11 files with no single source; left as is.LOCALESnames two different sets in the two suites (lines 114, 159);enumTablesnever clearsfield(lines 89-100);rubricCategoriesis a prose heuristic (lines 103-109).v2moves" and "what triggers a version bump" rules inCLAUDE.mdare inferred from tag history.Review
.DS_Storebrittleness, positionalrelatedvs consolidate sort, false "leaves a log entry" claimsrc/for the test: no shipped-code change for a test's convenience), unique: hard-coded docs inventory, loops inside oneit.github/andaction.ymldiff is comments and descriptions only, confirmed by the thermo reviewer🤖 Generated with Claude Code
(Claude)