agentleFS
house-of-giantshouse-of-giants/projectskills/skills/requirements-from-decisions/SKILL.md

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.

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
  1. Distinctive:

    Use this skill to create or update requirements that include:

    line 16
  2. Distinctive:

    Do not assume requirements belong inside a production code repo.

    line 34
  3. Distinctive:

    Read it before drafting requirements.

    line 48
  4. Distinctive:

    Follow the project’s stated requirement format if it exists.

    line 50
  5. Distinctive:

    If the requirement format is missing, use the default structure in this skill.

    line 51
  6. Distinctive:

    If it does not exist:

    line 53
  7. Distinctive:

    Do not invent approval rules, trackers, repos, or reviewers.

    line 56
  8. Distinctive:

    Read it after project context.

    line 69
  9. Very specific:

    Use Accepted decisions as the default source set.

    line 70
  10. Very specific:

    Treat Candidate decisions, Deferred / rejected decisions, and Open questions as constraints, blockers, proposed requirements, or …

    line 71
  11. Distinctive:

    Ask whether decision capture should happen first when the source material is a transcript, email thread, issue discussion, or meeting notes.

    line 77
  12. Distinctive:

    Do not mine full transcripts for requirements unless the user explicitly asks for that broader extraction.

    line 78
  13. Distinctive:

    Use the narrowest useful scope:

    line 82
  14. Very specific:

    All accepted decisions in .agents/decisions.md, if the user asks for full requirement drafting.

    line 84
  15. Distinctive:

    Before processing many decisions, state the intended source set and proceed if it matches the request.

    line 89
  16. Distinctive:

    Do not turn every accepted decision into a product requirement.

    line 107
  17. Very specific:

    Use explicit requirement statuses that cannot be confused with implementation or acceptance.

    line 113
  18. Distinctive:

    If a requirement represents a demo, preview, migration, or closeout path rather than core product behavior, name it that way in the …

    line 114
  19. Very specific:

    When candidate-derived ideas are included because the user asked or they are useful, put them in a separate Proposed requirements from …

    line 115
  20. Very specific:

    Use REQ-001, REQ-002, etc.

    line 177
  21. Very specific:

    Use NG-001, NG-002, etc. for non-goals.

    line 178
  22. Very specific:

    Use CON-001, CON-002, etc.

    line 179
  23. Very specific:

    Use RULE-001, RULE-002, etc.

    line 180
  24. Very specific:

    Use RQ-001, RQ-002, etc. for open requirement questions.

    line 181
  25. Distinctive:

    Do not renumber existing requirements unless the user explicitly asks.

    line 183
  26. Very specific:

    Use concise semicolon-separated checks inside the table for simple requirements.

    line 187
  27. Distinctive:

    Only add subsections when the table would become unreadable.

    line 199
  28. Distinctive:

    After writing or updating requirements, summarize:

    line 203
  29. Very specific:

    Read .agents/project-context.md before .agents/decisions.md when available.

    line 214
  30. Distinctive:

    Do not cite transcripts directly if an accepted decision already captures the transcript source.

    line 216
  31. Very specific:

    Do not turn candidate decisions into committed requirements by default.

    line 217
  32. Distinctive:

    Do not hide open questions by writing vague acceptance criteria.

    line 218
  33. Very specific:

    Do not invent actors, reviewers, execution trackers, or acceptance criteria.

    line 219
  34. Distinctive:

    If a later decision supersedes an earlier decision, update or mark affected requirements instead of silently deleting them.

    line 220
  35. Distinctive:

    not mixed with raw transcript notes or implementation plans

    line 231
  36. Distinctive:

    Use the section headings from the template unless the user requests a different structure.

    line 235
  37. Distinctive:

    Use markdown tables for requirement categories.

    line 236
  38. Distinctive:

    Keep each row short; add detail subsections only when necessary.

    line 237
  39. Very specific:

    Use stable status labels from the requirement status legend.

    line 238
  40. Distinctive:

    Keep source decision refs inline in each row.

    line 239

≈ “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

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.md

Do 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.md

If it exists:

  1. Read it before drafting requirements.
  2. Identify stakeholders, source systems, requirement format, execution tracker, repository workflow, review rules, constraints, and non-goals.
  3. Follow the project’s stated requirement format if it exists.
  4. If the requirement format is missing, use the default structure in this skill.

If it does not exist:

  1. Continue only if the user supplied enough decision context to draft requirements.
  2. Do not invent approval rules, trackers, repos, or reviewers.
  3. Recommend creating project context afterwards if the requirement output reveals recurring workflow rules.

Step 2: Read decisions

Look for:

.agents/decisions.md

If it exists:

  1. Read it after project context.
  2. Use Accepted decisions as the default source set.
  3. Treat Candidate decisions, Deferred / rejected decisions, and Open questions as constraints, blockers, proposed requirements, or future-work notes — not as committed implementation requirements.
  4. Preserve decision IDs as source refs.

If it does not exist:

  1. Continue only if the user supplied accepted decisions directly.
  2. Ask whether decision capture should happen first when the source material is a transcript, email thread, issue discussion, or meeting notes.
  3. 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:

  1. All accepted decisions in .agents/decisions.md, if the user asks for full requirement drafting.
  2. A named decision ID or small set of decision IDs.
  3. A named milestone, feature, or scope area.
  4. 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 typeMeaning
Functional requirementUser/system behavior that must exist.
Acceptance criterionObservable check for requirement completion.
Non-goalExplicitly excluded behavior or scope.
ConstraintRule that limits implementation choices.
Review ruleHuman approval or review requirement.
Execution noteTracker/repo/PR convention, not product behavior.
Open questionMissing 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 ready or Ready for execution trace over a bare Ready.
  • 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 candidates section with PREQ-* 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 two

Only 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.md before .agents/decisions.md when 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 candidates when 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 TBD or 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; use Requirement ready so 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.md was read when available.
  • .agents/decisions.md was 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, or Superseded rather than ambiguous bare Ready.
  • 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.

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.