What happened
A downstream cycle (medieval-factions-dev-loop, generated from this template) implemented an upstream issue documenting undocumented mf.force.* permission overrides. The issue was well-written, cited exact file paths, and had itself been filed by a previous dev-loop cycle that stated every claim was "verified by reading the command source." Three of its behavioral claims were nonetheless wrong — e.g. it said mf.force.kick "bypasses the normal role/permission check", but the source uses the permission only to select which faction is resolved, then still runs the normal role check against that faction and refuses on null. Documenting the issue's version verbatim would have shipped false statements into project docs.
The gap
Phase 3's Localization verification step (create-dev-loop.md:244-247) is explicitly about existence: "confirm the named entity is present" via grep. It does not ask whether the issue's description of what that entity does is correct. The Phase 1 filing-time verification ("Before filing each issue, verify every claim against source") is a different instruction at a different time, and — as this case shows — an issue can pass its own filing-time verification and still be wrong, because "this permission exists and is checked here" is much cheaper to verify than "and here is what happens after it is checked."
This matters most for documentation-generating cycles (one cycle files an issue, a later cycle implements it by writing docs) because the issue text is the most tempting thing to paraphrase directly into the docs, and there is no test that fails if you do.
Suggested instruction text
Add a third step to Phase 3's Localization verification (after the existing two):
- Confirm the issue's behavioral claims, not just the symbol's existence. For each behavior the issue asserts ("X bypasses the permission check", "Y defaults to Z"), read the surrounding code path to the point where the behavior would actually be observable — for a permission node, that means reading past the branch that consults it to whatever check runs next. If the issue's description and the source disagree, the source wins: implement/document what the code does, and file a separate issue for the discrepancy. Never paraphrase an issue body into documentation without this confirmation.
This is template-wide rather than repo-specific: any dev-loop that chains cycles (one cycle filing issues, a later cycle implementing them) can compound a mis-description in exactly this way, and the fix belongs in the shared Localization verification step rather than being re-derived per instance.
Originally filed against dmccoystephenson/medieval-factions-dev-loop#23 and routed upstream per that skill's template-rule policy.
What happened
A downstream cycle (
medieval-factions-dev-loop, generated from this template) implemented an upstream issue documenting undocumentedmf.force.*permission overrides. The issue was well-written, cited exact file paths, and had itself been filed by a previous dev-loop cycle that stated every claim was "verified by reading the command source." Three of its behavioral claims were nonetheless wrong — e.g. it saidmf.force.kick"bypasses the normal role/permission check", but the source uses the permission only to select which faction is resolved, then still runs the normal role check against that faction and refuses onnull. Documenting the issue's version verbatim would have shipped false statements into project docs.The gap
Phase 3's Localization verification step (create-dev-loop.md:244-247) is explicitly about existence: "confirm the named entity is present" via grep. It does not ask whether the issue's description of what that entity does is correct. The Phase 1 filing-time verification ("Before filing each issue, verify every claim against source") is a different instruction at a different time, and — as this case shows — an issue can pass its own filing-time verification and still be wrong, because "this permission exists and is checked here" is much cheaper to verify than "and here is what happens after it is checked."
This matters most for documentation-generating cycles (one cycle files an issue, a later cycle implements it by writing docs) because the issue text is the most tempting thing to paraphrase directly into the docs, and there is no test that fails if you do.
Suggested instruction text
Add a third step to Phase 3's Localization verification (after the existing two):
This is template-wide rather than repo-specific: any dev-loop that chains cycles (one cycle filing issues, a later cycle implementing them) can compound a mis-description in exactly this way, and the fix belongs in the shared Localization verification step rather than being re-derived per instance.
Originally filed against dmccoystephenson/medieval-factions-dev-loop#23 and routed upstream per that skill's template-rule policy.