agentleFS
l-gevityl-gevity/l-gevity-skills/.claude/skills/requirements-topology/SKILL.md

requirements-topology

Skill88 starsChanged 3 days agoMITView on GitHub

Structures validated requirements into an atomic, traceable, typed dependency graph and derives a trustworthy dependency order. Use when normalizing requirement wording, preserving stable IDs, splitting or merging requirements, modeling dependencies and constraints, detecting duplicates, conflicts, cycles, orphans, stale references, or missing verification, refining requirement-scope boundaries, or producing a graph package. Do not use for initial problem discovery or implementation planning.

The file

Show its rules and text

We split this skill into the rules it gives an agent

30 rules. About 0 are common, 22 are distinctive, and 8 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈22

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 8

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Very specific:

    Use requirements-grounding first when the problem, actor, basis, scope, priority, complete-when conditions, or validation decision is …

    line 38
  2. Distinctive:

    Read project instructions, domain glossaries, source catalogs, and policy files before structuring domain requirements.

    line 43
  3. Very specific:

    Use project-defined labels when present.

    line 80
  4. Distinctive:

    Do not create a second acceptance-criterion scheme.

    line 84
  5. Distinctive:

    Use typed directed edges and keep direction consistent:

    line 89
  6. Very specific:

    Default presentation direction: A -> B means “A depends on B.” Label the direction wherever ambiguity is possible.

    line 102
  7. Very specific:

    Treat depends_on as an acyclic projection.

    line 106
  8. Distinctive:

    Add typed edges supported by source evidence or an explicit inference note.

    line 119
  9. Distinctive:

    Run graph checks before deriving order.

    line 120
  10. Distinctive:

    Do not delete a requirement merely because it looks redundant.

    line 148
  11. Very specific:

    Do retire what an accepted replacement supersedes.

    line 151
  12. Distinctive:

    When requirements live in a repository, keep four responsibilities explicit:

    line 158
  13. Distinctive:

    Keep requirement status, approval, readiness, implementation, and verification as independent facts.

    line 176
  14. Distinctive:

    Use stable acceptance-criterion IDs when downstream tests or evidence must reference individual completion conditions.

    line 180
  15. Distinctive:

    If the second consumer is speculative, keep the prerequisite local until the reuse is real.

    line 204
  16. Very specific:

    Use structural-simplification when a proposed regrouping claims to reduce complexity.

    line 207
  17. Distinctive:

    Patch: update canonical requirements directly only when the user requests source edits and the meaning is settled.

    line 218
  18. Distinctive:

    Every application emits a decision record before any longer graph package:

    line 225
  19. Distinctive:

    Keep one place per fact:

    line 263
  20. Distinctive:

    Put relationship evidence in the edge list, not in repeated dependency columns.

    line 265
  21. Distinctive:

    Keep dependency order as an ordered list without repeating its edges.

    line 266
  22. Distinctive:

    Keep historical slugs in lineage only.

    line 269
  23. Distinctive:

    Do not rewrite legal, contractual, product, or stakeholder meaning to make the graph cleaner.

    line 278
  24. Distinctive:

    Do not infer service boundaries, synchronous calls, or event flows from graph edges.

    line 280
  25. Distinctive:

    Do not hide uncertainty by converting an inference into a source fact.

    line 282
  26. Distinctive:

    Do not claim the graph is stable while cycles, must-have verification gaps, unresolved ID transformations, or aspect-coverage failures …

    line 283
  27. Very specific:

    Do not report a cycle failure without inspecting the depends_on projection.

    line 285
  28. Very specific:

    Do not report an aspect-coverage failure without both holds_across and the constrains edges.

    line 287
  29. Distinctive:

    Do not hand-edit generated views or let them become a competing requirement source.

    line 289
  30. Distinctive:

    If grounding changes materially, refresh the topology or state exactly what is stale.

    line 291

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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 Topology

Turn grounded requirement candidates into a stable graph whose structure can be inspected, challenged, and used for sequencing without changing requirement meaning.

Core Directives

  1. Grounding remains canonical. The topology is a derived view, not a new source of truth.
  2. Reuse stable IDs. Preserve readable slugs through every derived artifact.
  3. One node, one obligation or outcome. Split compound nodes before adding edges.
  4. Type and evidence every relationship. Prose-only dependencies are hidden coupling.
  5. Order is derived, not authored. Compute build order from depends_on edges; never infer dependencies from document order.
  6. Graph structure is not software architecture. An edge does not imply an API, event, service, or deployment boundary.
  7. Operationalize one canonical model. Schemas, semantic checks, generated views, and CI gates must derive from the same requirement source instead of creating parallel authorities.

Boundary

Use requirements-grounding first when the problem, actor, basis, scope, priority, complete-when conditions, or validation decision is unclear. Use implementation-readiness after this skill when developers and architects need capabilities, increments, contracts, ADR seeds, tests, or a readiness decision.

Read project instructions, domain glossaries, source catalogs, and policy files before structuring domain requirements. Preserve project terminology and source hierarchy, but keep domain policy out of this generic model.

This topology describes requirement relationships, not subsystem placement. Do not assign Domain / abstraction tier / layer coordinates here; use morphogenetic-architecture when software subsystems need placement, observed-field analysis, or import constraints.

Requirement Record

Normalize each requirement into this minimal record:

id: readable-slug
statement: One atomic, solution-free outcome or obligation
actor: one actor
role: foundation | workflow | output | constraint | evidence-primitive | decision-input
kind: capability | business-rule | data | integration | security | compliance | operational
requirement_scope: owning problem scope or foundation capability
holds_across: []
priority: must | should | could | won't-now
status: draft | accepted | deprecated | superseded | lapsing
basis: authoritative | interpreted | evidenced | hypothesized
source_refs: []
complete_when_ref: requirement source location
notes: ""

lapsing marks an accepted retirement whose implementation removal has not landed. A lapsing record carries the expiry condition that ends it.

holds_across lists the requirement scopes, or all, that a constraint node binds; a node with it is an aspect. It normalizes grounding's Holds across, and the edge list is the evidence it is checked against: every scope it names receives a constrains edge from the node.

Use project-defined labels when present. Keep the structural role and the domain kind separate: constraint explains how a node behaves in the graph; security may explain its subject.

Do not create a second acceptance-criterion scheme. Grounding's complete-when conditions are the acceptance criteria. Reference them and flag gaps.

Edge Taxonomy

Use typed directed edges and keep direction consistent:

A depends_on B      # A cannot be satisfied unless B exists first
A enables B         # A makes B possible but is not strictly required
A constrains B      # A limits valid ways to satisfy B
A verifies B        # A proves or checks B
A produces B        # A creates an output or state consumed by B
A duplicates B      # A likely overlaps B
A conflicts_with B  # A and B cannot both hold without a decision
A refines B         # A is a more specific expression of B

Default presentation direction: A -> B means “A depends on B.” Label the direction wherever ambiguity is possible. Mark inferred edges and state why the inference is necessary.

Treat depends_on as an acyclic projection. Runtime or business feedback loops may exist, but they must not be disguised as static prerequisite cycles.

Workflow

  1. Inventory grounded requirements and their source artifacts.
  2. Reuse current readable slug IDs. Mint new slugs only for genuine splits, merges, or newly inferred requirements; record lineage.
  3. Normalize each statement into one atomic outcome without changing meaning.
  4. Reference the existing complete-when conditions and flag unusable or missing verification.
  5. Assign role, kind, requirement-scope owner, priority, status, basis, and source lineage.
  6. Add typed edges supported by source evidence or an explicit inference note.
  7. Run graph checks before deriving order.
  8. Refine subsystem boundaries by cohesion: data ownership, decision owner, lifecycle, change reason, and test surface.
  9. Topologically sort the depends_on projection.
  10. Produce the smallest output mode that answers the user's decision.

Graph Checks

Check explicitly for:

  • missing, duplicate, or opaque IDs;
  • compound requirements that need splitting;
  • orphan nodes with no justified independence;
  • cycles in the prerequisite projection;
  • duplicate or conflicting requirements;
  • requirements without usable complete-when conditions;
  • stale references after renames, splits, or merges;
  • two active records or criteria for one obligation after a replacement was accepted (a predecessor that was never retired);
  • a split, merge, replacement, or retirement announced in prose instead of recorded in lineage fields;
  • constraints hidden inside workflow prose;
  • an aspect whose holds_across names a scope with no constrains edge into it;
  • external prerequisites without an owner or minimal contract;
  • source references that no longer match the grounding artifact;
  • requirement-scope clusters with mixed owners, lifecycles, or test surfaces.

Do not delete a requirement merely because it looks redundant. Mark the edge, preserve lineage, and propose the consolidation decision.

Do retire what an accepted replacement supersedes. The change that accepts the replacement marks the predecessor superseded, or lapsing with the condition that ends it, in the same change. Two active records for one obligation is a blocking lineage issue, not a watch item.

Repository Operationalization

When requirements live in a repository, keep four responsibilities explicit:

  1. Canonical inputs own meaning and accepted relationships. Human-authored requirement text and structured metadata must agree or fail validation.
  2. Schema validation checks record shape, required fields, enums, and ID syntax as early as editor tooling permits and again in blocking CI.
  3. Semantic validation checks global uniqueness, criterion IDs, reference resolution, alias ambiguity, lineage, dependency cycles, ownership, aspect coverage (every scope a node's holds_across names receives a constrains edge from it), and cross-record invariants that a file schema cannot prove. For lineage: a record that names a replacement has its predecessor retired or lapsing; a lapsing record carries an expiry condition; lineage announced only in prose fails.
  4. Generated views such as registers, diagrams, dependency order, code constants, and summaries are deterministic, marked read-only, and checked for drift in CI.

Keep requirement status, approval, readiness, implementation, and verification as independent facts. For example, an approval state may require an approval date, but it never implies implementation or passed evidence.

Use stable acceptance-criterion IDs when downstream tests or evidence must reference individual completion conditions. Preserve active IDs across edits; record aliases, splits, merges, replacements, and deprecated criteria without recycling identifiers. Every deprecation record also names the implementation artifacts reviewed against the retirement and an accountability reference for the decision.

For migrations, freeze the imported source with a revision or checksums, keep an old-to-new ID/path map, prove structural and semantic equivalence, and remove the temporary importer after the canonical source and rollback evidence are durable.

The repository gate should expose separate commands or phases for validation, generation, generated-drift checking, and traceability. A single aggregate requirements check should run them at the earliest project validation stage and again as an unbypassable CI backstop. Use requirements-traceability for live implementation and executed-evidence relationships.

Requirement-Scope Heuristics

Group requirements when they share data ownership, decision ownership, lifecycle, change reason, and test surface. Split when outputs, owners, persistence lifecycles, or verification strategies differ materially.

Promote a shared foundation only when multiple requirement scopes genuinely depend on it. If the second consumer is speculative, keep the prerequisite local until the reuse is real.

Use structural-simplification when a proposed regrouping claims to reduce complexity. Report its exact coder-facing fields: Subsystem-kinds Δ, Dependency-edges Δ, Max-chain-depth Δ, and Subsystem-count Δ. Do not substitute visual neatness for those measurements.

Modes

  • Analysis: report inventory, proposed nodes and edges, graph issues, and recommended changes without editing the source.
  • Hybrid: produce analysis, then apply only small unambiguous source edits such as IDs, headings, or explicit constraint labels.
  • Patch: update canonical requirements directly only when the user requests source edits and the meaning is settled.
  • Graph package: produce the normalized topology consumed by implementation-readiness.

Output Contract

Every application emits a decision record before any longer graph package:

Subject:           <requirement scope or source set>
Mode:              analysis | hybrid | patch | graph-package
Decision:          STABLE | NEEDS-REFACTOR | BLOCKED
Canonical source:  <grounding artifact and version>
Graph size:        <node count / typed-edge count>
Cycle:             Pass | Fail | Not evaluated
Aspect coverage:   Pass | Fail: <aspect → scope> | Not evaluated
Blocking issues:   <IDs, cycles, conflicts, verification, ownership, lineage, or aspect coverage>
Retired:           <IDs superseded or lapsing in this change, or none>
Inferred edges:    <count and evidence status>
Repository gate:   <schema / semantics / generated drift / not configured>
Next action:       <split, merge, source, decide, fix cycle, or run implementation-readiness>
Verification:      <graph checks and source comparisons run, or Not run + reason>

Aspect coverage: Fail yields NEEDS-REFACTOR when the uncovered scope has a node the aspect should constrain, and BLOCKED when the scope has no requirement at all — a meaning gap that returns to grounding.

A full graph package additionally contains:

Requirements topology:
- Meta-context:             # standalone artifacts only
- Reader guide:
- Source and lineage:
- Transformations:          # real splits, merges, retirements, inferred requirements
- Vocabulary:               # roles, edge types, graph direction
- Requirement records:
- Edge list:                # single source for relationships + evidence
- Dependency order:         # lean derived view of depends_on
- Diagram:                  # optional faithful derived view
- Attention list:           # issue | decision | watch

Keep one place per fact:

  • Put relationship evidence in the edge list, not in repeated dependency columns.
  • Keep dependency order as an ordered list without repeating its edges.
  • Include a Mermaid diagram only when it faithfully represents the relevant edge list; omit a decorative or lossy graph.
  • Keep historical slugs in lineage only. Use current slugs everywhere active.
  • Collapse graph issues, open decisions, and source-watch items into one typed attention list.

For a standalone artifact, state audience, purpose, completion date, canonical source, source currency, and caveats once near the top.

Guardrails

  • Do not rewrite legal, contractual, product, or stakeholder meaning to make the graph cleaner.
  • Do not infer service boundaries, synchronous calls, or event flows from graph edges.
  • Do not hide uncertainty by converting an inference into a source fact.
  • Do not claim the graph is stable while cycles, must-have verification gaps, unresolved ID transformations, or aspect-coverage failures remain.
  • Do not report a cycle failure without inspecting the depends_on projection; use Not evaluated and name the missing graph input instead.
  • Do not report an aspect-coverage failure without both holds_across and the constrains edges; use Not evaluated and name the missing input.
  • Do not hand-edit generated views or let them become a competing requirement source.
  • If grounding changes materially, refresh the topology or state exactly what is stale.

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.