ntanh1402/sdlc-skills

sdlc-write-stories

Break the Requirements of a Feature or ChangeRequest in the project wiki into user stories, while they are a draft or once they are agreed - one actor goal each, "As a … I want … so that …", with numbered pass/fail acceptance criteria that cite the Requirem…

Voir la source

Mode d’emploi

  1. Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
  2. Consultez le document original pour les outils, identifiants et environnements requis.
  3. Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/ntanh1402/sdlc-skills --skill sdlc-write-stories

Avant de commencer

  • L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
  • Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Document Skill original

Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.

Write the user stories

This skill is a lifecycle step after the Requirements are written; they may still be a draft. It runs at the same time as sdlc-design-arch on the same target; neither waits for the other. It takes a Feature or ChangeRequest and writes STORY-<name>.md files into its folder, so that every Functional Requirement that is not Wont is listed by at least one story.

Stories are optional: a Feature or ChangeRequest without them is planned, tested and built as before. A story groups Requirements; it never adds behaviour. The Requirements stay the testable unit.

Its draft prefix is stories-: the draft for FEAT-coupons is wiki/stories-FEAT-coupons.

Before you start

Read, in this skill's folder, references/read-protocol.md; each section names the other references/ files to read when it starts.

Find the wiki as the read protocol says, and check that it matches this skill. RELEASE, next to this file, holds one line such as 1.0.0:

bash
cd "$WIKI" && $T copy check --release "<the line in RELEASE>"
statusDo
currentGo on
olderStop: "The wiki's tool is older than this skill. Run sdlc-setup-wiki to upgrade the wiki."
newerStop: "The wiki was set up by a newer release. Update your installed sdlc-skills."
editedStop: "The wiki's tool copy was edited by hand. Run sdlc-setup-wiki to restore it."

Then read the schema pages schema.md, user-story.md, feature.md, change-request.md and task.md in the wiki's .wiki-llm/schema/.

RequestSkill
New or changed Requirements, or a criterion no Requirement supportssdlc-write-spec
Architecturesdlc-design-arch
Build tasks, or linking Tasks to storiessdlc-plan-tasks
Test cases or suitessdlc-design-story-tests for one story, sdlc-design-feature-tests for flows across stories
Create or update tickets in the trackerNo skill does: a person pastes the story and may add trackerKey and resource to it (sdlc-edit-wiki)
Show a story, or its paste-ready copy againsdlc-ask-wiki
A typo in a storysdlc-edit-wiki

The gates

A gate is a stop for the person's explicit approval. There are three, so the person decides what is being done (Intent, section 2), how (Design, section 3), and exactly what is saved (Change-set, section 5), each before the next cost is paid.

  • Approval is an explicit yes to the gate's question. "Sounds good", silence

or "whatever you think" is not approval.

  • An edit at a gate reopens that gate and every later one.
  • When you cannot ask the person (a run with no one to answer), or the person

asks you to skip questions or approvals ("don't ask me, just write it"), stop before the first gate and start no draft. Return the open decisions and the gates the work still needs. Never assume approval.

  • When the person rejects the design, stop. A draft worktree this run started

is discarded; a worktree an earlier run started is left as it is.

  • Being asked to run this skill does not approve anything it writes.
  • A refusal this file states is a refusal. Do not turn it into a question.

1. Look up: readiness and the inventory

Accept one FEAT-* or CR-* key, or find it as sdlc-write-spec does (a key the user gave, an exact title, the Feature whose outcome owns the behaviour). Read it on the default branch:

StateWhenDo
READYA Feature Draft, ReqApproved, Approved or InDev, or a ChangeRequest Proposed, ReqApproved or Approved; and coverage stories reports Requirements, outdated lists a story, or the person asks to revise the storiesGo on
NOT_MERGEDNot on the default branch, but a wiki/*-<Key> draft existsStop and name the draft
CLOSEDA Feature Released or Deprecated, or a ChangeRequest Implemented or RejectedStop: a change to a Released Feature goes through a ChangeRequest (sdlc-write-spec)
ALREADY_CURRENTcoverage stories and outdated report nothing and the person asks for nothing to changeReport the stories and stop
bash
$T coverage stories --feature FEAT-coupons      # or --change CR-sms-alerts
$T outdated --feature FEAT-coupons              # stories written from an older spec version

When the Requirements are still a draft, say so in the first round: the stories may have to change when the spec does. A story outdated lists was written from an older version: compare its Requirements at that version with the current ones (git log -p on the overview.md), and revise it only when the change touches it; a story you revise is rewritten whole.

Every state but READY is a refusal, not a question.

Then read the Requirements, the PRD (the Reference the Feature or ChangeRequest links under # References), the stories already in the folder, and the Tasks that link them. For a ChangeRequest, also read the changed Feature's stories that list a Requirement the ChangeRequest changes (same key).

Build the inventory: each Requirement with its key, priority and type, marked needs a story (Functional, not Wont) or optional; and the actors and goals the PRD names.

An unfinished run. Last, ls "$WIKI"/.worktrees/*/plan.md 2>/dev/null lists the runs that stopped part-way. When one is for this request (its folder is stories-<Key>, or its plan's title names this request), read references/write-protocol.md now and go on as its section 2 says, without asking the rounds again.

2. Questions and the Intent gate

Read references/story-rules.md now.

Ask in rounds. A round is a numbered list of every question that can be answered now, each with your recommended answer, so the person confirms or corrects instead of composing an answer:

text
Q1 - How should the coupon Requirements be grouped into stories?
     (features/FEAT-coupons/overview.md)
     ➡️ Two stories: STORY-coupons-apply-at-checkout and STORY-coupons-remove-coupon.
Q2 - What else in the wiki must change because of this?
     ➡️ Nothing: only story files and the folder's log.
  • A recommendation that rests on the wiki cites the path. A question whose

answer depends on another question in the same round waits for the next round.

  • Ask at least one round, even when a brief seems complete: its questions are

then the assumptions you would otherwise make without saying so.

  • Which questions to ask, and how many, is your judgement.
  • Always ask the wiki question: what else in the wiki must change because of

this request, with your own answer as the recommendation.

  • Wait for the answers, and ask another round when they open new questions.

Search the wiki again whenever an answer brings a system, a term or a claim about current behaviour you have not read. When nothing that changes the output is left undecided, go to the Intent gate: one approval, after the rounds.

The first round names the target and its state, shows the inventory, and proposes the stories: key, actor, goal and the Requirements each lists, split as references/story-rules.md says. It asks the choices that are the person's:

  • where one goal is cut into two stories;
  • which actor a story is for when the PRD names several;
  • the priority of each story;
  • for a ChangeRequest, which Feature stories it affects.

When the brief or the person already names stories, take them as given, with their wording: propose only the tracing, and report what they leave uncovered. Do not split, merge or reword them yourself.

A criterion the person wants that no Requirement supports is not written. It is a gap in the Requirements: name it under "For other skills" for sdlc-write-spec, in the Run plan and in the summary. When the stories cannot be written without it, stop before the Intent gate and name sdlc-write-spec as the skill to run first.

The wiki question's usual answer is "nothing: only story files and the folder's log".

Intent gate. Restate the target, the inventory and the proposed stories (key, actor, goal, Requirements). Ask for approval.

3. Run plan and the Design gate

Read references/write-protocol.md and references/story-format.md now.

Start or resume the draft stories-<Key> as write-protocol.md section 2 and section 3, "At section 3", say. The input paths are the target's overview.md and, for a ChangeRequest, the changed Feature's overview.md and the Feature stories it affects.

Prepare every story in full, with references/story-format.md: the sentence, the numbered pass/fail criteria with real values, the Requirements, and for a ChangeRequest # Affects. Prepare the coverage matrix: each Requirement of the inventory to the stories that list it, and each optional Requirement no story lists.

Write the Run plan (write-protocol.md section 4). Its ## Files are one line per story file, added, changed or deleted, with its goal in a few words, each Task or other story whose link to a deleted story is dropped, and each log.md changed.

Design gate. Show every story as it will be written, never only a summary, then the coverage matrix, then the Run plan. Ask for approval.

4. Write

In the draft worktree, in the Feature's or ChangeRequest's folder, write each story as STORY-<feature-name>-<name>.md, with basedOn: { version: <the folder's Feature or ChangeRequest version>, at: <its versionDate> }. In a revision, keep each existing story's key, rewrite each story you touch whole in the current form (references/story-rules.md, "Revisions"), and give each story you revise, or checked against the new version, the current basedOn. Delete a story whose Requirements were all removed, or that was folded into another story, and change the links to it, as "Revisions" in references/story-rules.md says. Add an entry to the folder's log.md, for example * **Stories**: Wrote 3 user stories. Written by an AI model with sdlc-write-stories.

Do not touch overview.md, the PRD or the changed Feature's stories, and change a Task only to drop or replace a link to a deleted story. Linking Tasks to the stories is sdlc-plan-tasks. Do not write index.md, # Changed by or # Test cases: draft finish does.

Input check. sdlc-design-arch may merge while this draft is open, and it writes the same overview.md (its # Architecture or # Delta, and the status). When the input check of write-protocol.md section 3 shows that file changed, compare only its # Requirements between READ and the default branch. The same Requirements: the input did not change for this step; go on. Different: show what changed and go back to section 3.

5. Self review, finish and commit

Read references/paste-format.md now. Follow write-protocol.md section 3, "At section 5". In the self review (write-protocol.md section 5), have the review sub-agent check by reading (with references/story-rules.md) that:

  • each story is one actor's goal on one surface and passes the INVEST check

of references/story-rules.md;

  • no story is made only of RULEs of another story's SPINE;
  • each criterion is a pass/fail statement with real values and cites only

Requirements its story lists;

  • no file outside the story files and the folder's log.md changed, except

a dropped or replaced link to a deleted story and its log entry;

  • every story of the folder has the current basedOn.

Then run $T coverage stories (which must report nothing) and $T validate (no story.* or ids.story-format finding) in the worktree.

Commit message: stories(<Key>): <n> user stories, for example stories(FEAT-gift-cards): 3 user stories.

Before the summary, print the paste-ready copy of each story added or changed, as references/paste-format.md shows. It is not written to the wiki. Then end with at most four lines:

text
Done: wiki/stories-FEAT-coupons, 3 files, pushed. Open the pull request.
Not done: STORY-coupons-stacking (needs a new Requirement first)
For other skills: REQ-coupons-stacking is missing (sdlc-write-spec)
Next: sdlc-plan-tasks once the design is merged.

Leave out "Not done" and "For other skills" when they have nothing to say. Do not list what the self review fixed, and do not repeat the stories. "Next" is "sdlc-plan-tasks once the design is merged, even while the Requirements are a draft"; when the folder already has Tasks, "run sdlc-plan-tasks again to link the stories".

Done when

  • The target and the proposed stories were confirmed in the rounds, and the

intent was approved at the Intent gate.

  • Every story was shown in full and approved at the Design gate.
  • Every Functional Requirement that is not Wont is listed by a story;

every criterion cites a listed Requirement, and every listed Requirement is cited.

  • The self review found nothing it could not fix, or the person accepted what

was left at the Change-set gate.

  • coverage stories reports nothing, draft finish was ok, the change set

was approved, draft commit reported the branch, and the paste-ready copy was printed.

du même dépôt

Autres Skills

Tous les Skills
ntanh1402
Communauté

sdlc-ask-wiki

Answer questions from the project wiki without changing it - list an application's Features with status, spec version, owner, priority, design readiness and open ChangeRequests; list what was written from an older version of a spec; show one Feature's approved architecture with its diagrams, services, frontends, contracts, decisions, traceability and what is not built yet; show one Endpoint or consumer with its input, output, validations and diagrams; show a user story or print its paste-ready c

Installations / 1h
2
GitHub Stars
1
Mis à jour
13 nov.
ntanh1402
Communauté

sdlc-build-task

Write the code and unit tests of one wiki Task in one code repository, against the project wiki - read the Task's acceptance and planned scope, the contracts of the Design files it covers and the Application's conventions, plan the files, write them in a git worktree on a branch of their own, check them against the wiki and commit with a Task trailer, without pushing. Use when a developer asks to build, implement or code a Task of the project wiki. Not for coding without a wiki Task, for changin

Installations / 1h
2
GitHub Stars
1
Mis à jour
13 nov.
ntanh1402
Communauté

sdlc-close-task

Record in the project wiki that the code of one wiki Task is merged - set the Task Done with its merge commit, remove the pending entries of the Design files it covered and mark them live, and move its Feature to InDev or its ChangeRequest to Implemented. Use after a Task's pull request is merged, when a developer asks to close, finish or complete a Task in the wiki. Not for closing a ticket in a tracker, for merging or reviewing code, for marking a Feature released, or for any other change of s

Installations / 1h
2
GitHub Stars
1
Mis à jour
13 nov.
ntanh1402
Communauté

sdlc-convert-doc

Convert local documents into Markdown by routing text-bearing files through Microsoft MarkItDown and OCR-heavy inputs through Datalab Marker. Use when asked to convert PDFs, scanned PDFs, images, Word, PowerPoint, Excel, HTML, EPUB, email, archives, or other document files to Markdown, especially when OCR, tables, equations, layout preservation, or extraction-quality fallback is needed.

Installations / 1h
2
GitHub Stars
1
Mis à jour
13 nov.