You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Should a plugin flag a new markdown file the task did not ask for, at write time? #15654
Should a plugin flag, at write time, a new doc, rule or note file the task did not ask for?
From the talk
Chapter 5, slide 20: agents escape into unsolicited markdown; stop it.
Today and the gap
No write-time gate exists. /docs-hygiene:audit-derivability judges a doc's value only afterwards.
Recommendation
Investigate (menu priority P1): a write-time guard in the guardrails or docs-hygiene plugin that flags, not blocks, a new markdown file outside the task's stated outputs. Basis: the gap above; judgment on false positives.
Alternatives
Block instead of flag; leave it to the after-the-fact audit; a prose rule only (the weakest ladder tier).
Done would add
A hook or check in guardrails or docs-hygiene, configurable per repository. Dogfood: enabled in this repository and its flag count reported over a set period.
Size: Medium
Complexity: Medium
Uncertainty: Knowable
Flags: intent
Blocked by: none
Understood: you want a write-time hook that flags (not blocks) a new markdown file outside the task's stated outputs, configurable per repository, and enabled here as a dogfood. No merged pull request or open issue looks like it already covers this. Two design choices are open:
Which plugin owns the hook: guardrails or docs-hygiene? RECOMMENDED: guardrails. It already owns write-time hooks, while docs-hygiene audits after the fact. Basis: your "Today and the gap" section.
Flag or block? RECOMMENDED: flag only, with the mode configurable. Basis: your false-positive concern.
The dogfood measurement over a set period can't be run unattended. It can be tracked separately.
To answer, post a comment that starts with this line:
Resolved: declined. No plugin adds a write-time rule for new markdown files.
From the talk. Slide 20 ("stop agents from writing unsolicited markdown", 1:08:26) and the transcript at 1:07:56 to 1:08:26: agents use "documentation, code comments, rules or skills" as "a place to write down their justifications for not doing the right thing", or "over-rotate on some small correction ... and they treat it like a hard rule".
Why no deterministic rule.
A hook cannot decide the thing that matters, whether the task asked for the file. It can only see a new markdown file at a path.
In this repository markdown is the product. Of the 1,073 markdown files added in the last 300 commits on main (counted 2026-11-12 with git log -300 --diff-filter=A --name-only -- "*.md"), 927 are changelog fragments, 101 eval case files, 32 plugin reference pages, 8 skill files and 5 decision or upstream records. None landed anywhere else. A flag on every new file would be noise; a flag only outside those paths would have fired zero times.
Owner, 2026-11-12: "I mean we create a lot of .md files in this repo that ship as plugins/skills..?" and "yeah idk if we can/should have a deterministic rule here".
What covers the talk's point instead.
After the fact, /docs-hygiene:audit-derivability judges whether a doc earns its place.
A correction that keeps recurring goes to /corrections:codify, which counts recurrence before proposing a rule, the guard against one correction hardening into a rule.
Reopen when a markdown file nobody asked for is found merged in a melodic-software or kyle-sexton repository, or a consumer repository where markdown is not the product asks for the guard. The shape to start from then: flag only outside the paths the repository declares as markdown homes, in the guardrails plugin.
Basis: the talk passages above; the count above; the owner's words. The count sees merged files only, so a stray file written and removed before merge would not show.
Activity
github-actions commentedon Nov 12, 2026
Size: Medium
Complexity: Medium
Uncertainty: Knowable
Flags: intent
Blocked by: none
Understood: you want a write-time hook that flags (not blocks) a new markdown file outside the task's stated outputs, configurable per repository, and enabled here as a dogfood. No merged pull request or open issue looks like it already covers this. Two design choices are open:
The dogfood measurement over a set period can't be run unattended. It can be tracked separately.
To answer, post a comment that starts with this line:
Automated triage. A maintainer reviews it.
melodic-automation-lanes commentedon Nov 12, 2026
The triage verdict left this issue at
needs-owner-decision:Reason:
intentkyle-sexton commentedon Nov 12, 2026
kyle-sexton commentedon Nov 13, 2026
Resolved: declined. No plugin adds a write-time rule for new markdown files.
From the talk. Slide 20 ("stop agents from writing unsolicited markdown", 1:08:26) and the transcript at 1:07:56 to 1:08:26: agents use "documentation, code comments, rules or skills" as "a place to write down their justifications for not doing the right thing", or "over-rotate on some small correction ... and they treat it like a hard rule".
Why no deterministic rule.
main(counted 2026-11-12 withgit log -300 --diff-filter=A --name-only -- "*.md"), 927 are changelog fragments, 101 eval case files, 32 plugin reference pages, 8 skill files and 5 decision or upstream records. None landed anywhere else. A flag on every new file would be noise; a flag only outside those paths would have fired zero times.What covers the talk's point instead.
/docs-hygiene:audit-derivabilityjudges whether a doc earns its place./corrections:codify, which counts recurrence before proposing a rule, the guard against one correction hardening into a rule.Reopen when a markdown file nobody asked for is found merged in a melodic-software or kyle-sexton repository, or a consumer repository where markdown is not the product asks for the guard. The shape to start from then: flag only outside the paths the repository declares as markdown homes, in the guardrails plugin.
Basis: the talk passages above; the count above; the owner's words. The count sees merged files only, so a stray file written and removed before merge would not show.
kyle-sexton commentedon Nov 13, 2026
Resolved; see the resolution comment.