story-update
Skill0 starsChanged 3 months agoMITView on GitHub
Refresh a GitHub implementation story from the current repository solution. Use when a user provides a GitHub issue URL and asks to update the story with features already implemented, manually added behavior, or requirements missing from the original story, while preserving the repository story-guardian format and returning one copyable Markdown block.
In this repository12 other files it gives its agents.
- AGENTS.mdAGENTS.md
- backend-doc-syncSkill
- check-documentation-gapsSkill
- check-test-gapsSkill
- commiterSkill
- docs-guardianSkill
- monthly-doc-actualizerSkill
- release-note-writerSkill
- story-checkSkill
- story-guardianSkill
- tech-debtSkill
- test-scenario-guardianSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
21 rules. About 0 are common, 19 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈19
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 8
Update an existing GitHub story so it describes the current repository solution as if the implementation had not yet started.
- Distinctive: line 20
Do not guess a repository or issue number when the URL is missing or malformed.
- Distinctive: line 21
Read the issue with the GitHub MCP issue-read tool first.
- Distinctive: line 22
Read the issue body and use comments only as supporting context.
- Distinctive: line 24
Do not modify the GitHub issue, add comments, change labels, or change issue state.
- Distinctive: line 37
Check git status --short and inspect relevant working-tree diffs.
- Distinctive: line 41
Follow the actual code path far enough to verify behavior, not just symbol existence.
- Distinctive: line 42
Search for related routes, workflow functions, database tables, configuration values, feature flags, tests, and documentation references.
- Distinctive: line 56
Do not describe the result as already implemented inside the replacement story.
- Distinctive: line 57
Do not invent behavior that cannot be supported by repository evidence.
- Distinctive: line 60
Keep the story outcome-focused.
- Very specific: line 65
Follow the applicable structure and section order defined in documentation/story_template.md, using .agents/skills/story-guardian/SKILL.md …
- Very specific: line 69
Use concise, story-specific acceptance criteria and keep Definition of Done short and reusable.
- Distinctive: line 77
Do not place explanatory text before or after that code block when delivering the final story.
- Distinctive: line 79
Do not use nested triple-backtick fences inside the story.
- Distinctive: line 82
Do not create or modify repository files unless the user separately requests that.
- Distinctive: line 83
Do not write the updated story back to GitHub.
- Distinctive: line 104
If GitHub issue retrieval fails, report the exact retrieval error and do not fabricate the issue's title or body.
- Distinctive: line 106
If the repository implementation cannot be inspected, report the exact limitation and do not claim that the story is synchronized with …
- Distinctive: line 108
If the issue is a parent story, keep the result broad and do not force it into a technical implementation story.
- Distinctive: line 118
all applicable story-guardian sections.
≈ “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
Story Update
Update an existing GitHub story so it describes the current repository solution as if the implementation had not yet started. Treat the current code, database, tests, and documentation as the source of truth for the updated story, while treating the original GitHub issue as the source of the declared intent.
Required workflow
1. Resolve the story URL
- Extract the GitHub owner, repository, and issue number from the user-provided URL.
- Accept a full issue URL as the primary input, for example:
https://github.com/owner/repository/issues/123. - Do not guess a repository or issue number when the URL is missing or malformed.
- Read the issue with the GitHub MCP issue-read tool first.
- Read the issue body and use comments only as supporting context; do not promote comments into requirements unless the user explicitly asks for that.
- Do not modify the GitHub issue, add comments, change labels, or change issue state.
2. Load story standards
- Read
documentation/story_template.md. - Read
.agents/skills/story-guardian/SKILL.md. - Apply the technical implementation-story structure when the issue describes a deliverable requiring implementation context and verification.
- Preserve the original story number and intent unless the repository evidence requires a clearer title.
3. Inspect the current solution
- Check
git status --shortand inspect relevant working-tree diffs. Include uncommitted implementation and documentation changes in the comparison. - Inspect the implementation files, API schemas, database migrations/functions/views, tests, test scenarios, and related documentation relevant to the issue.
- Follow the actual code path far enough to verify behavior, not just symbol existence.
- Search for related routes, workflow functions, database tables, configuration values, feature flags, tests, and documentation references.
- Record repository-relative evidence internally while drafting the story.
4. Reconstruct the story as pre-implementation work
- Pretend the current solution has not yet been implemented.
- Convert every confirmed implemented behavior into story requirements, proposed changes, acceptance criteria, tests, and documentation synchronization items.
- Include behavior that was added manually or exists in the repository but is absent from the original story.
- Include required compatibility changes, such as removing an obsolete API route, adding a replacement route, preserving a compatibility field, or updating public response contracts.
- Do not describe the result as already implemented inside the replacement story.
- Do not invent behavior that cannot be supported by repository evidence.
- Explicitly record important behavior that is not implemented when it could otherwise be mistaken for part of the story.
- Keep the story outcome-focused; move detailed evidence into concise references and implementation bullets.
5. Apply story-guardian structure
Follow the applicable structure and section order defined in
documentation/story_template.md, using .agents/skills/story-guardian/SKILL.md as
the governing refinement guidance.
Use concise, story-specific acceptance criteria and keep Definition of Done short and
reusable. Split the story only when the current scope contains independently deliverable
outcomes that cannot reasonably be reviewed together.
6. Produce copyable output
- Print the complete replacement story in exactly one Markdown fenced code block using
the
mdlanguage marker. - Do not place explanatory text before or after that code block when delivering the final story; the block must have one-click copy behavior in the client.
- Do not use nested triple-backtick fences inside the story. Use indented examples or four-tilde fences inside the outer block if examples are required.
- Include the Story Guardian Report inside the same Markdown block.
- Do not create or modify repository files unless the user separately requests that.
- Do not write the updated story back to GitHub.
Current-solution comparison rules
Classify findings internally as:
- Implemented behavior to add — confirmed in current code but absent from the issue.
- Story requirement preserved — stated in the issue and supported by current code.
- Story requirement corrected — stated differently from current behavior; rewrite it to match the current solution.
- Current behavior explicitly out of scope — present in the repository but not part of the story's user-visible outcome; mention only when necessary to prevent ambiguity.
- Unsupported requirement — present in the issue but not supported by current code; retain it only if it is clearly part of the intended story, and identify it as pending rather than claiming implementation evidence.
The final story should describe the complete intended change, not a review table. Use
repository paths in References and in pre-reading lists to make the story actionable.
Failure handling
- If GitHub issue retrieval fails, report the exact retrieval error and do not fabricate the issue's title or body.
- If the repository implementation cannot be inspected, report the exact limitation and do not claim that the story is synchronized with current behavior.
- If the issue is a parent story, keep the result broad and do not force it into a technical implementation story. If it is a numbered technical story, use the full technical template.
Output requirements
The final response must contain:
- one complete, copyable
mdcode block; - a story title aligned with the original issue;
- all applicable story-guardian sections;
- acceptance criteria covering both original requirements and confirmed additional implementation behavior;
- a
Story Guardian Reportstating the story type, normalized sections, scope-splitting assessment, and one result:Compliant,Updated to compliant, orPartially compliant.
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.

