Skip to content

Should a plugin flag a new markdown file the task did not ask for, at write time? #15654

Closed

Description

@kyle-sexton

Question

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.

Activity

  1. added
    wayfind: interviewWayfind decision item: contract/requirements call the user must make; human in the loop.
    needs-humanHuman-in-the-loop required; autonomous sessions must not resolve items carrying this.
    on Nov 12, 2026
  2. added theissue type on Nov 12, 2026
  3. github-actions commented on Nov 12, 2026

    @github-actions
    Contributor

    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:

    1. 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.
    2. 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:

    **Decision recorded.** <answer>
    

    Automated triage. A maintainer reviews it.

  4. added
    needs-owner-decisionAwaiting a human or maintainer judgment call.
    needs-triageNot yet classified. Floor until a type and one priority tier are set.
    on Nov 12, 2026
  5. melodic-automation-lanes commented on Nov 12, 2026

    @melodic-automation-lanes
    Contributor

    The triage verdict left this issue at needs-owner-decision:

    • flagged: intent
    • held by needs-owner-decision
    • held by needs-human
    • no lanes App verdict comment shows whether an earlier verdict was flagged

    Reason: intent

  6. self-assigned this
    on Nov 12, 2026
  7. kyle-sexton commented on Nov 12, 2026

    @kyle-sexton
    MemberAuthor
    No description provided.
  8. kyle-sexton commented on Nov 13, 2026

    @kyle-sexton
    MemberAuthor

    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.
    • The code-comment half of her point is its own item: Adopt the no-comments posture here and support it as a plugin setting.
    • 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.

  9. kyle-sexton commented on Nov 13, 2026

    @kyle-sexton
    MemberAuthor

    Resolved; see the resolution comment.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

needs-humanHuman-in-the-loop required; autonomous sessions must not resolve items carrying this.needs-owner-decisionAwaiting a human or maintainer judgment call.needs-triageNot yet classified. Floor until a type and one priority tier are set.wayfind: interviewWayfind decision item: contract/requirements call the user must make; human in the loop.

Type

Fields

Work status

needs-human

Priority

medium

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions