requirements-from-decisions
Skill2 starsChanged 6 months agoMITView on GitHub
When the user wants to turn accepted project decisions into implementation-ready requirements, acceptance criteria, non-goals, or requirement drafts. Reads `.agents/project-context.md` and `.agents/decisions.md` first when available, uses accepted decisions by default, keeps candidates/open questions out of requirements unless explicitly requested, and writes structured markdown requirements with decision source references.
In this repository6 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- decision-captureSkill
- execution-traceSkill
- project-contextSkill
- workspace-initSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
40 rules. About 0 are common, 25 are distinctive, and 15 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈25
Distinctive · estimate
This author's own choices. Worth a look.
15
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
Use this skill to create or update requirements that include:
- Distinctive: line 34
Do not assume requirements belong inside a production code repo.
- Distinctive: line 48
Read it before drafting requirements.
- Distinctive: line 50
Follow the project’s stated requirement format if it exists.
- Distinctive: line 51
If the requirement format is missing, use the default structure in this skill.
- Distinctive: line 53
If it does not exist:
- Distinctive: line 56
Do not invent approval rules, trackers, repos, or reviewers.
- Distinctive: line 69
Read it after project context.
- Very specific: line 70
Use Accepted decisions as the default source set.
- Very specific: line 71
Treat Candidate decisions, Deferred / rejected decisions, and Open questions as constraints, blockers, proposed requirements, or …
- Distinctive: line 77
Ask whether decision capture should happen first when the source material is a transcript, email thread, issue discussion, or meeting notes.
- Distinctive: line 78
Do not mine full transcripts for requirements unless the user explicitly asks for that broader extraction.
- Distinctive: line 82
Use the narrowest useful scope:
- Very specific: line 84
All accepted decisions in .agents/decisions.md, if the user asks for full requirement drafting.
- Distinctive: line 89
Before processing many decisions, state the intended source set and proceed if it matches the request.
- Distinctive: line 107
Do not turn every accepted decision into a product requirement.
- Very specific: line 113
Use explicit requirement statuses that cannot be confused with implementation or acceptance.
- Distinctive: line 114
If a requirement represents a demo, preview, migration, or closeout path rather than core product behavior, name it that way in the …
- Very specific: line 115
When candidate-derived ideas are included because the user asked or they are useful, put them in a separate Proposed requirements from …
- Very specific: line 177
Use REQ-001, REQ-002, etc.
- Very specific: line 178
Use NG-001, NG-002, etc. for non-goals.
- Very specific: line 179
Use CON-001, CON-002, etc.
- Very specific: line 180
Use RULE-001, RULE-002, etc.
- Very specific: line 181
Use RQ-001, RQ-002, etc. for open requirement questions.
- Distinctive: line 183
Do not renumber existing requirements unless the user explicitly asks.
- Very specific: line 187
Use concise semicolon-separated checks inside the table for simple requirements.
- Distinctive: line 199
Only add subsections when the table would become unreadable.
- Distinctive: line 203
After writing or updating requirements, summarize:
- Very specific: line 214
Read .agents/project-context.md before .agents/decisions.md when available.
- Distinctive: line 216
Do not cite transcripts directly if an accepted decision already captures the transcript source.
- Very specific: line 217
Do not turn candidate decisions into committed requirements by default.
- Distinctive: line 218
Do not hide open questions by writing vague acceptance criteria.
- Very specific: line 219
Do not invent actors, reviewers, execution trackers, or acceptance criteria.
- Distinctive: line 220
If a later decision supersedes an earlier decision, update or mark affected requirements instead of silently deleting them.
- Distinctive: line 231
not mixed with raw transcript notes or implementation plans
- Distinctive: line 235
Use the section headings from the template unless the user requests a different structure.
- Distinctive: line 236
Use markdown tables for requirement categories.
- Distinctive: line 237
Keep each row short; add detail subsections only when necessary.
- Very specific: line 238
Use stable status labels from the requirement status legend.
- Distinctive: line 239
Keep source decision refs inline in each row.
≈ “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
Requirements From Decisions
You help users turn accepted project decisions into clear, source-linked requirements.
This skill is for requirements drafting and requirements maintenance. It is not for broad project context, raw transcript review, ticket creation, or implementation planning. Start from .agents/project-context.md and .agents/decisions.md when available. Use accepted decisions by default.
What this skill does
Use this skill to create or update requirements that include:
- requirement IDs
- source decision IDs
- actors / users
- requirement statements
- acceptance criteria
- non-goals and exclusions
- reviewer / approver
- execution target when known
- open questions or blocked items
The output is structured markdown, usually at:
.agents/requirements.mdDo not assume requirements belong inside a production code repo. They may live in a project workspace above one or more repos.
Workflow
Step 1: Read project context first
Look for:
.agents/project-context.mdIf it exists:
- Read it before drafting requirements.
- Identify stakeholders, source systems, requirement format, execution tracker, repository workflow, review rules, constraints, and non-goals.
- Follow the project’s stated requirement format if it exists.
- If the requirement format is missing, use the default structure in this skill.
If it does not exist:
- Continue only if the user supplied enough decision context to draft requirements.
- Do not invent approval rules, trackers, repos, or reviewers.
- Recommend creating project context afterwards if the requirement output reveals recurring workflow rules.
Step 2: Read decisions
Look for:
.agents/decisions.mdIf it exists:
- Read it after project context.
- Use
Accepted decisionsas the default source set. - Treat
Candidate decisions,Deferred / rejected decisions, andOpen questionsas constraints, blockers, proposed requirements, or future-work notes — not as committed implementation requirements. - Preserve decision IDs as source refs.
If it does not exist:
- Continue only if the user supplied accepted decisions directly.
- Ask whether decision capture should happen first when the source material is a transcript, email thread, issue discussion, or meeting notes.
- Do not mine full transcripts for requirements unless the user explicitly asks for that broader extraction.
Step 3: Choose the requirement scope
Use the narrowest useful scope:
- All accepted decisions in
.agents/decisions.md, if the user asks for full requirement drafting. - A named decision ID or small set of decision IDs.
- A named milestone, feature, or scope area.
- Requirements update only for changed decisions.
Before processing many decisions, state the intended source set and proceed if it matches the request.
Step 4: Convert accepted decisions into requirements
For each accepted decision, decide whether it creates:
| Output type | Meaning |
| Functional requirement | User/system behavior that must exist. |
| Acceptance criterion | Observable check for requirement completion. |
| Non-goal | Explicitly excluded behavior or scope. |
| Constraint | Rule that limits implementation choices. |
| Review rule | Human approval or review requirement. |
| Execution note | Tracker/repo/PR convention, not product behavior. |
| Open question | Missing detail that blocks requirement completeness. |
Rules:
- Do not turn every accepted decision into a product requirement.
- Scope decisions and non-goals should become constraints or non-goals.
- Workflow decisions should become review/execution rules only if useful for implementation.
- Candidate decisions should not become requirements unless the user explicitly asks for draft/proposed requirements.
- Open questions should stay open and should mark affected requirements as blocked, partial, or needing verification when they affect acceptance.
- Requirements should be testable enough for later ticketing or PR review.
- Use explicit requirement statuses that cannot be confused with implementation or acceptance. Prefer
Requirement readyorReady for execution traceover a bareReady. - If a requirement represents a demo, preview, migration, or closeout path rather than core product behavior, name it that way in the requirement statement and status.
- When candidate-derived ideas are included because the user asked or they are useful, put them in a separate
Proposed requirements from candidatessection withPREQ-*IDs and needed-confirmation notes. - Split combined proposed requirements when one part is a blocker/source dependency and another part is UX polish or implementation detail.
Step 5: Write or update .agents/requirements.md
Use this structure:
# Requirements
Status: active
Last updated: YYYY-MM-DD
## Requirement sources
| Source | Type | Date | Location | Notes |
|---|---|---|---|---|
## Requirement status legend
- `Requirement ready`: source-linked requirement ready for trace, ticketing, or review; not implemented or accepted.
- `Blocked`: open question or source dependency prevents completion.
- `Proposed`: candidate-derived requirement that is not accepted scope.
- `Verified`: implementation/verification evidence exists; client or reviewer acceptance may still be separate.
- `Accepted`: project-defined reviewer/client acceptance evidence exists.
- `Superseded`: replaced by a later decision or requirement.
## Functional requirements
| ID | Source decision refs | Actor / user | Requirement statement | Acceptance criteria | Non-goals / scope guards | Reviewer / approver | Execution target | Verification evidence | Status |
|---|---|---|---|---|---|---|---|---|---|
## Proposed requirements from candidates
These are useful candidate-derived drafts, not accepted requirements. Promote only after the project-defined reviewer confirms them or a canonical decision source is updated.
| ID | Source candidate / question | Proposed requirement | Needed confirmation | Affected committed requirement |
|---|---|---|---|---|
## Non-goals and constraints
| ID | Type | Item | Source decision | Notes |
|---|---|---|---|---|
## Review and execution rules
| ID | Rule | Source decision | Applies to | Notes |
|---|---|---|---|---|
## Open requirement questions
| ID | Question | Source | Blocks | Owner | Status |
|---|---|---|---|---|---|
## Change log
| Date | Change | Source |
|---|---|---|ID format:
- Use
REQ-001,REQ-002, etc. for functional requirements. - Use
NG-001,NG-002, etc. for non-goals. - Use
CON-001,CON-002, etc. for constraints. - Use
RULE-001,RULE-002, etc. for review/execution rules. - Use
RQ-001,RQ-002, etc. for open requirement questions. - Preserve existing IDs when updating a file.
- Do not renumber existing requirements unless the user explicitly asks.
Acceptance criteria format:
Use concise semicolon-separated checks inside the table for simple requirements. Include execution target and verification evidence as TBD when unknown instead of inventing issue IDs, PRs, checks, or reviews. If a requirement needs more detail, add a short subsection below the table:
### REQ-001 — Short title
Source decision: D-001
Acceptance criteria:
- [ ] Criterion one
- [ ] Criterion twoOnly add subsections when the table would become unreadable.
Step 6: Report the requirement cutline
After writing or updating requirements, summarize:
- decision IDs used
- requirements created or updated
- non-goals / constraints captured
- candidate decisions intentionally excluded or separated as
PREQ-* - open questions blocking requirements
- recommended next skill, if useful
Source handling rules
- Read
.agents/project-context.mdbefore.agents/decisions.mdwhen available. - Preserve source decision IDs in every requirement row.
- Do not cite transcripts directly if an accepted decision already captures the transcript source; cite the decision ID instead.
- Do not turn candidate decisions into committed requirements by default; keep them in
Proposed requirements from candidateswhen useful. - Do not hide open questions by writing vague acceptance criteria.
- Do not invent actors, reviewers, execution trackers, or acceptance criteria. Mark missing detail as
TBDor add an open requirement question. - If a later decision supersedes an earlier decision, update or mark affected requirements instead of silently deleting them.
Output standard
A good .agents/requirements.md is:
- compact enough to scan
- structured enough for ticketing and PR review
- explicitly linked to accepted decisions
- honest about blockers and unknowns
- clear about what is out of scope
- not mixed with raw transcript notes or implementation plans
Formatting rules:
- Use the section headings from the template unless the user requests a different structure.
- Use markdown tables for requirement categories.
- Keep each row short; add detail subsections only when necessary.
- Use stable status labels from the requirement status legend. Avoid bare
Ready; useRequirement readyso downstream agents do not confuse requirement readiness with implementation or acceptance. - Keep source decision refs inline in each row.
Common pitfalls
- Treating candidate decisions as approved requirements.
- Converting workflow decisions into product requirements.
- Losing the decision ID that explains why a requirement exists.
- Inventing acceptance criteria that were not supported by decisions or project context.
- Creating tickets before requirements are reviewable.
- Hiding open questions inside vague requirement language.
- Labeling a preview/demo path as generic product acceptance.
- Combining unrelated candidate ideas into one proposed requirement when they have different blockers or confirmation paths.
- Duplicating rejected scope as future work instead of recording it as a non-goal.
Verification checklist
Before finishing:
.agents/project-context.mdwas read when available..agents/decisions.mdwas read when available.- Only accepted decisions became committed requirements by default.
- Candidate/deferred/open items were kept separate unless explicitly requested.
- Every requirement has a source decision or source marked
TBD. - Non-goals and constraints are visible.
- Requirement statuses use
Requirement ready,Blocked,Proposed,Verified,Accepted, orSupersededrather than ambiguous bareReady. - Candidate-derived items, if included, are separated as proposed requirements and not mixed into committed requirements.
- Open requirement questions are visible.
- Existing IDs were preserved on update.
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.

