agentleFS
haruharu/redmine_ai_helper/.claude/skills/record-spec-feedback/SKILL.md

record-spec-feedback

Skill107 starsChanged 9 months agoMITView on GitHub

Record a user's correction of an AI-written specification in docs/spec-feedback/ as an append-only entry with root-cause analysis. Use right after applying a user-requested fix to spec.md, plan.md, tasks.md, or a design document (AGENTS.md and the constitution require this), or when the user asks to log spec feedback. Skips typo-only and wording-only fixes.

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 5 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Consider any context from the user input (which feedback to record, which feature, the user's own view of the cause) before proceeding.

    line 19
  2. Very specific:

    Read docs/spec-feedback/README.md.

    line 25
  3. Distinctive:

    Stop without recording if every point is a typo fix or a wording change that does not change meaning, and tell the user why.

    line 37
  4. Distinctive:

    If the request contains several points, group them by root cause: one entry per root cause.

    line 39
  5. Very specific:

    Create docs/spec-feedback/NNN-short-title.md from the template, in English, with today's date.

    line 62
  6. Distinctive:

    Never edit or delete existing entries, except for updating the Promoted to field in Step 7.

    line 65
  7. Distinctive:

    Write entries in English regardless of the conversation language.

    line 85
  8. Very specific:

    Keep excerpts short, but make each entry self-contained: specs/ is gitignored, so quote the lines needed to understand the correction …

    line 86

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Record Spec Feedback

Record a correction the user requested on an AI-written specification, analyze why the AI wrote it that way, and derive a rule that prevents the same mistake next time.

User Input

$ARGUMENTS

Consider any context from the user input (which feedback to record, which feature, the user's own view of the cause) before proceeding.

Procedure

Step 1: Read the Rules

Read docs/spec-feedback/README.md. It defines what to record, the root-cause categories, the template, and the index. Follow it; this skill only describes the workflow.

Step 2: Collect the Feedback

From the conversation and the working tree, identify:

  • The user's correction request (their words, translated faithfully into English if needed)
  • The affected feature (specs/NNN-... directory or branch) and artifact file
  • The original AI-written text and the corrected text — use git diff on the artifact, or the conversation history when the file is not tracked (specs/ is gitignored)

Record only corrections that have been applied. If the fix is not applied yet, apply it first.

Stop without recording if every point is a typo fix or a wording change that does not change meaning, and tell the user why.

If the request contains several points, group them by root cause: one entry per root cause.

Step 3: Check Existing Entries

Scan the index in the README and open entries with the same category or a similar topic. If an existing entry describes the same pattern, list it under Related.

Step 4: Analyze the Root Cause

Answer concretely:

  • What did the AI base the original text on (request wording, an existing spec, the code, a guess)?
  • What should it have read or asked instead — name the file, wiki page, ADR, or question?
  • Why did it not do so (information absent, ambiguity not noticed, convention not documented, over-generalization)?

Pick the category from the README table. Use other only with an explanation.

Step 5: Write the Prevention Rule

Write a rule that is concrete and checkable at spec-writing time (e.g. "When a spec introduces a new setting, state its default; ask the user if the request does not give one" — not "be more careful"). Set Promoted to to Not yet unless the rule is actually added to a durable place.

Step 6: Create the Entry

  1. Find the highest existing number in docs/spec-feedback/ and add one (start at 001).
  2. Create docs/spec-feedback/NNN-short-title.md from the template, in English, with today's date.
  3. Append a row to the README index: | [SF-NNN](./NNN-short-title.md) | Title | category | feature | Not yet |.

Never edit or delete existing entries, except for updating the Promoted to field in Step 7.

Step 7: Propose Promotion When It Recurs

If the new entry has two or more Related entries (the pattern has occurred at least three times), propose to the user where the prevention rule should be promoted (AGENTS.md, the constitution, a skill). A pattern that has occurred only twice is not proposed: promoting at two occurrences fills the durable files with rules. The proposal states:

  1. The destination: the file and the section the rule goes into.
  2. The exact text to add.
  3. What the rule requires, explained in the user's language, one item per requirement in the text: what to do, and when it applies.

The proposal is about the rule itself. Do not retell the findings, the entries, or the reasons for promoting it unless the user asks. Do not change those files without the user's approval. After the approved rule is added, update the entry's Promoted to field and the matching index cell to name the destination.

Propose promotion only for a rule that applies across features and areas of the codebase. Do not propose a rule tied to one feature, one component, or one kind of output (for example, only PDF export or only one screen), even when it has recurred: every promoted rule is loaded into every session's context, so a narrow rule costs context in all the sessions where it does not apply. Leave such a rule in the log entry with Promoted to set to Not yet, and do not mention promotion in the report.

Step 8: Report

Tell the user the created file, the category, the prevention rule, and any promotion proposal. Do not commit.

Notes

  • Write entries in English regardless of the conversation language.
  • Keep excerpts short, but make each entry self-contained: specs/ is gitignored, so quote the lines needed to understand the correction instead of linking to the artifact.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.