Identify capability boundaries
Derive capability candidates from the system's actual behavior and current implementation boundaries, not from folder names or idealized architecture.
Use kebab-case for capability names such as workspace-indexing, order-cancellation, report-export, or theme-customization.
Use these decomposition lenses as needed:
- Actor lens: who or what invokes the behavior
- Workflow lens: what end-to-end outcome the system produces
- Interface lens: API, command, event, page, protocol, or other interaction surface
- Modularity lens: what could realistically be implemented, added, replaced, disabled, or removed without redesigning the whole system
- Domain lifecycle lens: creation, approval, publication, reconciliation, archival, deletion, and similar transitions
- Runtime lens: scheduling, background work, startup, orchestration, retries, health checks, or resilience behavior
- Policy lens: validation, authorization, prioritization, quotas, deduplication, ownership, and other cross-cutting rules
The final capability list may contain any number of specs, be that 5- or 50 specs. The number of specs is not a quality metric; use the system and its boundaries to decide how many specs to create, not a feeling of what a good number of specs looks like. Remember creating these specs will be delegated to a host of other agents in seperate forks, so creating any number of specs is achievable.
Bias toward the smallest capability boundary that still produces a useful spec. If one broad candidate contains several slices that a team could implement or retire separately, split them.
In particular, do not group multiple providers, integrations, adapters, backends, external systems, or strategy implementations into one capability when each has its own behavior, mapping, configuration, runtime contract, or test surface. Prefer one spec per such slice, plus a separate shared-layer spec only if a real shared contract needs to be preserved.
Keep a candidate as its own capability when most of these are true:
- it has a distinct trigger, actor, interface, or runtime boundary
- it has a primary observable outcome that can be stated simply
- it carries rules or constraints that are not merely incidental details of a larger flow
- it could plausibly be implemented, modified, replaced, enabled, disabled, or removed with limited impact on adjacent slices
- it can be implemented, tested, or changed with a mostly local understanding
- a future maintainer could read this spec and know where to start
Split a candidate when:
- one document would bundle several providers, integrations, adapters, external systems, or strategy implementations that behave differently enough to be changed separately
- one document would otherwise mix unrelated outcomes or actors
- one part is a reusable policy or invariant that affects multiple workflows
- the implementation already treats the slices independently
- different slices have different configuration, mappings, state handling, persistence rules, external dependencies, or test anchors
- a team could reasonably add, remove, or swap one slice without rewriting the others
- the requirement list starts reading like a table of contents instead of one contract
Merge adjacent candidates when:
- they share the same trigger, outcome, and invariants
- they are not realistically implemented or changed independently
- splitting them would force developers to consult multiple thin specs to understand one real change
- the current implementation still treats them as one coherent workflow
Create broader system-layer or cross-cutting specs only when they describe infrastructure that multiple feature specs build on, such as shared orchestration, authorization policy, persistence conventions, event contracts, or runtime lifecycle rules.
Avoid these anti-patterns:
- naming capabilities after folders or layers instead of behavior
- creating entity-only specs when the real behavior is broader than one data type
- splitting conceptual sub-steps that are never triggered or reasoned about independently
- collapsing several modular features into one spec just because they belong to the same subsystem
- grouping multiple providers or integrations into a single spec when each one would merit its own implementation slice
- writing separate specs for exceptions when a single rule would stay clearer and more accurate
- letting a hoped-for architecture override the real system shape
Example of preferred granularity:
- prefer
holfuy-station-sync, metfrost-station-sync, portwind-station-sync, and windsmobi-station-sync
- only add a broader spec such as
weather-station-platform-contract if there is a real shared contract or layer that those separate specs build upon
Before writing any spec, prepare a candidate list with:
- capability name
- one-sentence purpose
- why it is separate from adjacent candidates
- primary trigger or entry point
- primary observable outcome
- why it is modular enough to deserve its own spec, or why it must remain a broader shared-layer spec
- strongest evidence anchors
Present the capability list and stop for user direction
After exploration, Reply with an enumerate list of specs followed by the "next step" section. For each one, include:
- capability name
- one-line purpose
Next step: Give the user these choices:
(make sure they are not a part of the list of specs, but seperate)
- Approve the list of specs and recieve guiding on creating them.
- Provide the user with different directions and modifcations to apply to the list provided. Based on alternative slicings and organizations that the user may consider instead. Spend a second thinking here, before
- Finally ask the user "Anything else you would like to change or discuss?"
Handle any custom answer or instruction given by the user, refining the list of specs, repeat until the user approves.
If the user chooses to approve, respond with Step 2 below and do not start writing specs in the same reply.
Step 2. Instruct the user to fork the conversation and handle one spec per fork. Tell the user to use this prompt in each fork:
"I want you to explore the codebase specifically and comprehensively in relation to this spec in the numbered list above. If you find an ambiguity that may materially affect the meaning, boundary, priority, or intent of the spec, and you cannot derive the answer from the codebase and project artifacts with enough confidence, ask me clarifying questions before you write the details for spec number: x"
Also instruct the user how to fork effectively:
