story issues

Stories

A story is a unit of customer-visible functionality — specific enough that a developer is confident they can build it and a customer is confident that if it's built, it will provide value.

Elements

Stories typically have several elements:

User story — A sentence (or a few) that names the actor, what they do, and why. Sometimes the "As a some role, I want some goal so that some reason" structure fits; sometimes it doesn't.

Scenario — A paragraph that starts from the world as it is right now (no assumed prior state unless it was established by an earlier story). Uses persona names, concrete artifacts (PR #42, boot()), and present tense.

Acceptance Tests — Each is a sequence of concrete steps with expected outcomes. They serve as:

• The customer's checklist: "if these pass, the story delivers value"
• The developer's spec: "if I make these pass, I'm done"
• A regression suite when automated

Technical Notes — Constraints and guidance for the implementor. Where a choice exists, the note flags the tradeoff but does not prescribe a solution.

Conventions

• Start from reality. If the governance system doesn't exist yet, the first story is about creating it — not about using it.

• Use personas, not real people's names. Stories may be public and collaborators have not all agreed to participate. Alex (Lead Steward), Dr. Rivera (Clinical Domain Steward), Sam (Contributor).

  Personas are reused across stories so readers learn who's who.

• Authorization is tested in both directions. The happy path works. The wrong-actor path is rejected.

• Acceptance tests do not prescribe implementation. They describe observable behavior. "The system records X" not "INSERT into table Y".

Origin

This project uses the story-driven development methodology described in Storytelling and Test Cases. Each story's acceptance tests are candidates for automated testing in the style of heron_policy.py doctests.