Create and maintain use case specifications following Cockburn format with semantic anchors and ubiquitous language. Use when writing use cases, specifying requirements, or documenting system behavior in AsciiDoc.
Creates business-readable use cases that serve both human stakeholders and AI implementation.
Always create AsciiDoc (.adoc) files in /docs/use-cases/.
DO:
DON'T:
Each step gets an anchor with the full step text as reftext:
. [[step-validate,System validates identity is new]] *System validates identity is new* +
_System queries whether <<IdentityProviderUser,identity>> already exists_
Extensions reference by anchor:
=== During <<step-validate>>: User Already Exists
Benefits:
step-validate identifierLink domain terms to definitions:
<<User>> - authentication entity<<Person>> - human being<<Account>> - resource/billing container<<IdentityProviderUser>> - external identity linkFirst create or reference the ubiquitous language in /docs/ubiquitous-language/.
= UC-XXX: {Name}
== Metadata
| Primary Actor | <<Person>> with {credentials}
| Scope | {Bounded Context}
| Level | User Goal
== Stakeholders and Interests
*{Stakeholder}*:: {What they want}
== Preconditions
* <<Person>> has {prerequisite}
== Postconditions
=== Success Guarantee
* <<User>> created
* <<DomainEvent>> published
== Main Success Scenario
. [[step-initiate,{Actor} initiates {action}]] *{Actor} initiates {action}* +
_{Business result}_
. [[step-validate,System validates {condition}]] *System validates {condition}* +
_{Validation logic}_
. [[step-create,System creates {entity}]] *System creates {entity}* +
_{Creation outcome}_
== Extensions (Alternative Flows)
=== During <<step-validate>>: {Condition}
*Condition:* {When this happens}
*Steps:*
. {Alternative action}
. *Resume:* Continue at <<step-create>>
=== During <<step-validate>>: {Failure}
*Condition:* {Failure condition}
*Steps:*
. {Failure handling}
. *ENDS* (failed)
== Technology and Data Variations
* {Technical options}
== Special Requirements
* {Business constraints}
== Open Issues
* [[issue-xxx]] {Question to resolve}
== Related Use Cases
* xref:uc-xxx.adoc[UC-XXX: Name]
| Pattern | Use When | Example |
|---|---|---|
| During <<step-anchor>> | Extension interrupts step | During <<step-validate>>: Invalid Input |
| After <<step-anchor>> | Extension follows step | After <<step-create>>: Send Notification |
| Resume at <<step-anchor>> | Return to main flow | Resume at <<step-complete>> |
| ENDS | Flow terminates | *ENDS* (success) or *ENDS* (failed) |
uc-{kebab-case}.adoc for use casesuc-{name}-contract.adoc for implementation contracts (if needed)See assets/uc-registration-example.adoc for a complete example.
<<Term>> references