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.
In this repository48 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .github/copilot-instructions.mdCopilot instructions
- commitSkill
- create-pull-requestSkill
- create-release-branchSkill
- create-release-notesSkill
- handle-pr-reviewSkill
- qlty-checkSkill
- record-code-review-feedbackSkill
- recreate-test-dbSkill
- redmine-playwright-loginSkill
- regression-checkSkill
- rubocopSkill
- speckit-agent-context-updateSkill
- speckit-analyzeSkill
- speckit-branch-convention-configureSkill
- speckit-branch-convention-renameSkill
- speckit-branch-convention-validateSkill
- speckit-checklistSkill
- speckit-clarifySkill
- speckit-constitutionSkill
- speckit-convergeSkill
- speckit-git-commitSkill
- speckit-git-featureSkill
- speckit-git-initializeSkill
- speckit-git-remoteSkill
- speckit-git-validateSkill
- speckit-implementSkill
- speckit-planSkill
- speckit-review-codeSkill
- speckit-review-commentsSkill
- speckit-review-errorsSkill
- speckit-review-runSkill
- speckit-review-simplifySkill
- speckit-review-testsSkill
- speckit-review-typesSkill
- speckit-specifySkill
- speckit-tasksSkill
- speckit-taskstoissuesSkill
- speckit-token-budget-compactSkill
- speckit-token-budget-conciseSkill
- speckit-token-budget-scopeSkill
- speckit-token-budget-usageSkill
- speckit-wiki-ingestSkill
- speckit-wiki-initSkill
- speckit-wiki-lintSkill
- speckit-wiki-querySkill
- speckit-wiki-statusSkill
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
- Distinctive: line 19
Consider any context from the user input (which feedback to record, which feature, the user's own view of the cause) before proceeding.
- Very specific: line 25
Read docs/spec-feedback/README.md.
- Distinctive: line 37
Stop without recording if every point is a typo fix or a wording change that does not change meaning, and tell the user why.
- Distinctive: line 39
If the request contains several points, group them by root cause: one entry per root cause.
- Very specific: line 62
Create docs/spec-feedback/NNN-short-title.md from the template, in English, with today's date.
- Distinctive: line 65
Never edit or delete existing entries, except for updating the Promoted to field in Step 7.
- Distinctive: line 85
Write entries in English regardless of the conversation language.
- Very specific: line 86
Keep excerpts short, but make each entry self-contained: specs/ is gitignored, so quote the lines needed to understand the correction …
≈ “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.
Files
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
$ARGUMENTSConsider 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 diffon 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
- Find the highest existing number in
docs/spec-feedback/and add one (start at001). - Create
docs/spec-feedback/NNN-short-title.mdfrom the template, in English, with today's date. - 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:
- The destination: the file and the section the rule goes into.
- The exact text to add.
- 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.
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
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.

