feat(map-explain): respect user language + cut wall-of-text verbosity (#224)#225
Merged
Merged
Conversation
…#224) `/map-explain` had two UX defects on real targets: output was hardcoded to English (ignoring the user's established language in context) and produced an enormous wall of text from the rigid always-emit-all-10-sections / explain-every-line structure (~4000 words on a 600-line diff). Rewrite both surfaces (Claude + Codex) from completeness-first to signal-first, per the LLM-council deliberation and the owner-validated worked template in the issue: - Add an explicit output-language rule near the top: prose in the user's established language; code, identifiers, commands, and `file:line` refs stay English. - Replace the 10-section checklist with an adaptive output spec: size tiers with word-budget ceilings + load-bearing-line caps, a front-loaded "Mental model in 60 seconds" block, read-tier section tags ([MUST READ]/[READ IF MODIFYING]/[SKIM]), a single load-bearing-lines table (merges old "what every line does" + "why each line"; repeated shapes explained once), before->after-first ordering for diffs, adaptive sections with an `Omitted:` footer, and natural-language follow-up offers. - Delete `do not skip "obvious" lines`; define load-bearing mechanically with a skip list and a worked filter example; ban filler openers; tighten the `Inferred:` rule. Edited the .jinja sources and re-rendered all generated trees. `make check` green (2511 passed, render parity ✅). Closes #224 Co-Authored-By: Claude Opus 4.8 (1M context) <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.
Summary
Fixes the two
/map-explainUX defects from #224:file:linerefs in English.Implements the LLM-council deliberation (council id in the issue) plus the owner-validated worked template from the issue comment. No re-consultation needed — the design was already settled and validated on a real 600-line Go controller diff.
What changed (both Claude + Codex surfaces)
[MUST READ], ≤100 words).[MUST READ]/[READ IF MODIFYING]/[SKIM]).Omitted:footer line.do not skip "obvious" lines; banned filler openers; tightened theInferred:rule.Invariants honored
.jinjasources intemplates_src/; ranmake render-templatesto propagate to all generated trees (.claude/,.agents/, bothtemplates/mirrors).make checkgreen: 2511 passed, 3 skipped, render parity ✅.releaseis a manual build + PyPI prompt); this is a skill-content change, no version bump.Closes #224
🤖 Generated with Claude Code