UserStory
A UserStory captures a high-level requirement from the perspective of a role. It maps to the classic As a / I want / so that format via the who, what, and why fields. why is optional (defaults to None), mirroring the optional dod field, since not every story carries a distinct justification worth writing out.
Stories are classified as functional or technical using UserStoryType.
The optional dod field holds a free-form definition of done. The tags field is an unordered set of short label strings for categorisation; tags from parent and child stories are merged as a union.
UserStory carries both the Historized mixin (with history: frozenset[UserStoryHistoryEntry]) and the Commentable mixin (with comments: frozenset[Comment]). Both fields accumulate across scope merges. See HistoryEntry and Comment.
The links field holds typed relationships to other UserStories. See Links for the full concept.
UserStoryType
UserStoryType
Bases: str, Enum
Classifies a UserStory as functional or technical.
UserStoryHistoryEntry
UserStoryHistoryEntry
Bases: HistoryEntry
A HistoryEntry specialised for UserStory changes.
Extends the base entry with sets of AC ids that were added, deactivated, or reassessed as part of the recorded change event.
Attributes:
| Name | Type | Description |
|---|---|---|
added_acs |
frozenset[int]
|
Integer ids of AcceptanceCriteria newly attached in this change. |
deactivated_acs |
frozenset[int]
|
Integer ids of AcceptanceCriteria deactivated in this change. |
reassessed_acs |
frozenset[int]
|
Integer ids of AcceptanceCriteria reassessed in this change. |
UserStory
UserStory
Bases: MergeableModel, Historized, Commentable
A high-level requirement scoped to an organizational unit.
Attributes:
| Name | Type | Description |
|---|---|---|
id |
int
|
Integer identifier, unique within the enclosing Scope. |
who |
str
|
The role or persona that wants the feature. |
what |
str
|
The capability or behaviour desired. |
why |
str | None
|
Optional free-form prose describing the business or technical justification. Defaults to None if unset. |
type |
UserStoryType
|
Whether the story is functional or technical. |
active |
bool
|
Whether this story is an active requirement.
Set to |
dod |
str | None
|
Optional free-form prose describing the definition of done. Defaults to None if unset. |
tags |
frozenset[str]
|
An unordered set of short label strings for categorisation. Defaults to an empty set. |
acceptance_criteria |
frozenset[AcceptanceCriterion]
|
The testable conditions defining completion. Each criterion's id must be unique within this story. |
links |
frozenset[UserStoryLink]
|
Typed relationships to other UserStories. Defaults to an empty set. |
is_validated
property
Return True when the story is active, has active criteria, and all are validated.
UserStoryLinkKind
UserStoryLinkKind
Bases: str, Enum
Classifies the nature of a relationship between two UserStories.
Attributes:
| Name | Type | Description |
|---|---|---|
RELATES_TO |
A loose, non-directional association. |
|
DEPENDS_ON |
The owning UserStory cannot be delivered until the target is. |
|
SUPERSEDES |
The owning UserStory replaces the target. |
UserStoryLink
UserStoryLink
Bases: BaseModel
A typed relationship from a UserStory to another UserStory.
Attributes:
| Name | Type | Description |
|---|---|---|
target_story_id |
int
|
The id of the related UserStory. |
kind |
UserStoryLinkKind
|
The nature of the relationship. |
provenance |
LinkProvenance
|
Whether the relationship was explicitly asserted or implicitly inferred. |