rai-story-design

Story Design

Purpose

Create a lean story specification optimized for both human review (clear intent) and AI alignment (accurate code generation).

Mastery Levels (ShuHaRi)

See raise.mastery in frontmatter.

Context

When to use: Before planning ANY story. Design is never optional — it is the gemba walk that prevents duplicate components, wasted effort, and wrong approaches.

Inputs: Story from backlog, User Story artifact (story.md from /rai-story-start), epic scope/design documents.

Steps

PRIME (mandatory — do not skip)

Before starting Step 1, you MUST execute the PRIME protocol:

1. Chain read: No chain read — story-design is the first skill in the story chain.
2. Graph query: Execute tier1 queries from this skill's metadata using the raise_graph_query MCP tool with cwd="{project_or_worktree_path}". If MCP tools are not available, fall back to:

   rai graph query
   

   If graph is unavailable, note and continue.
3. Present: Surface retrieved patterns as context. 0 results is valid — not a failure.
4. Code orientation: Load SA-ranked code symbols for the current branch using the raise_session_context MCP tool with sections="code_context", cwd="{project_or_worktree_path}". If MCP tools are not available, fall back to:

   rai session context -s code_context -p .
   

   Returns ~20 symbols ranked by structural proximity to active work modules. Empty result is valid — branch name may not match any module. Use these symbols as starting points for code exploration, not as exhaustive scope.
5. Backlog transition — engine owned (RAISE-15034): Transition to design status is performed by the pipeline engine via apply_phase_transition. No skill-initiated transition call required or allowed.

Step 1: Assess Complexity

JIT: Before assessing complexity, query graph for patterns from similar stories → aspects/introspection.md § JIT Protocol

Risk gate: If story is marked HIGH RISK in epic scope, discuss risks before designing — name concerns, failure modes, and scope boundaries.

UX gate: If story touches human interaction (workflows, prompts, DX), recommend /rai-research first (~10 min).

Integration gate: If story name includes "dogfood", "E2E", or "integration", OR if epic has separate client/server stories developed with mocks — AC MUST include at least one scenario that runs with real infrastructure (docker compose, actual DB, real HTTP calls). Unit tests with mocks cannot catch cross-component contract mismatches (auth headers, payload validation, parameter limits).

Frontend DoR gate (is_frontend=true only — skip for backend-only stories): Every screen referenced by this story (screen_refs) must be present in the prototype / living-design-system (prototype_screens). Formally: screen_refs ⊆ prototype_screens. If any referenced screen is absent, the story is NOT ready — extend the prototype first (add the missing screen faithful to existing tokens/components), then return to design. This is a lightweight DoR in Mike Cohn's sense ("sufficiently far along, not done") — not a pixel-final stage-gate and not BDUF. Skill-prose only; no new CLI verbs per ADR-125 / RAISE-10923.

Example (E11478): S5 (analytics dashboard) references the dashboard screen — that screen exists in the prototype → ready, proceed. S4 (subscription apply flow) references the apply screen — that screen is not yet in the prototype → NOT ready; extend the prototype with the apply screen first, then re-evaluate S4.

Step 2: Gemba Walk (mandatory — do not skip)

Go to the actual code. Design without reading the code is guessing.

1. Read what exists: Open and read the files/modules that this story will touch. Understand the current state before proposing changes.
2. Search for duplicates: Grep for similar functionality, components, or patterns that already exist. Before creating anything new, verify it doesn't exist already.
3. Check best practices: Look at how similar problems are solved in the codebase. Follow established patterns rather than inventing new ones.
4. Map dependencies: Identify what depends on the code you'll change, and what the changed code depends on.
5. Legacy sweep (mandatory): If this story introduces a V2 of something — new class, new module, new pattern that supersedes an existing one — answer in the design doc the question "what V1 becomes orphaned when V2 lands?". Three valid answers: (a) "nothing — this is net-new" (state it explicitly); (b) "V1 at file:line — deletion plan is X" (commit-level plan included); (c) "V1 coexists because Y" (explain why keeping V1 is correct). No implicit answers. This exists because RCA s2092.1 showed refactors cierran declarados done sin barrer V1 (R1/R3/R5 · pattern refactor-declared-done-without-sweep).

# Example gemba commands
grep -r "similar_function" packages/  # Does this already exist?
grep -r "class SimilarModel" packages/ # Duplicate models?

JIT: For deeper code exploration beyond the orientation map, use the raise_graph_query MCP tool with cwd="{project_or_worktree_path}" or fall back to CLI:

rai graph query "symbol_name" --types symbol --limit 10
rai graph query "module_name" --module mod-raise-cli--session
rai graph query "callers of function_name" --types symbol

Use --file path/to/file.py to scope results to a specific file.

Portfolio context — fail-open:

rai portfolio suggest "$JIRA_KEY" 2>/dev/null || true

If the command produces output, add a ## Portfolio Context section to the design doc with the raw output — include components_touched and change_mode to cross-check the gemba walk findings. If the story has no portfolio profile (empty output), retry with the parent epic key:

rai portfolio suggest "$EPIC_KEY" 2>/dev/null || true

If neither call produces output, continue without portfolio context — do not block.

Drift Risk Check — for each module this story will touch:

1. If governance/drift-hotspots.json exists: check if the module appears in the top-10 ranked modules — note rank and signal count.
2. Check governance/drift-catalog.md §1 (AG1–AG6): does the story scope risk any of these?
   • AG4 (context-window planning): does the change fan out across >3 modules with unresolved coupling edges?
   • AG2 (clone amplification): are you duplicating logic that exists elsewhere?
3. Flag risks in this design doc's Approach section as signals — not blockers. "No drift risk identified" is always valid.

Graceful degradation: if governance/drift-hotspots.json is absent, skip step 1 silently and proceed to step 2.

Step 3: Frame What & Why (informed by gemba)

Load story.md (from /rai-story-start) if it exists — use its User Story as starting frame.

JIT: Before framing problem and value, query graph for prior designs with similar scope → aspects/introspection.md § JIT Protocol

• Problem: What gap does this fill? (1-2 sentences)
• Value: Why does this matter? (1-2 sentences, measurable or observable)

Step 4: Describe Approach (lean principles)

JIT: Before describing approach, query graph for implementation patterns in affected modules → aspects/introspection.md § JIT Protocol

Document WHAT you're building and WHY this approach (not detailed HOW):

• Solution approach (1-2 sentences)
• Components affected (list with change type: create/modify/delete)

Lean design gates — challenge every component before committing:

• KISS: Is this the simplest approach that works? If not, simplify.
• DRY: Does this duplicate logic that exists elsewhere (gemba walk should have found it)?
• YAGNI: Are you building for a real requirement or a hypothetical one? Cut speculative features.
• MVP: What is the smallest version that delivers the value from Step 3? Build that, not more.

For refactoring: grep all call sites of the target. A half-migration is worse than none.

For data mutations: What happens when inputs reference missing entities? Declare the strategy explicitly: reject with error, skip + report count, partial success with warnings. Silent drops are semantic bugs.

Storage migration gate: If this story replaces a storage mechanism (file → SQLite, JSON → DB, YAML → table), answer for every public function of the replaced module: "What did callers get on (a) missing data and (b) corrupt data before? What will they get after?" Common silent contract breaks:

• FileNotFoundError → empty result (callers catching the exception silently get nothing)
• ValueError/JSONDecodeError → ValidationError (callers expecting None on corrupt data now get an exception)
• File mtime → no equivalent (staleness checks break silently)

Declare the contract explicitly in the Approach section and add an AC for each broken contract you identify. Skip this gate if the story does not replace a storage mechanism.

Also run — advisory ⚠ if stale or missing:

rai schema sum check

If stale, update:

rai schema sum update

Schema version coordination check: If this story adds a _V{N}_DDL migration, verify that the next version number is not already taken by the dev branch:

# Current branch version
grep "^SCHEMA_VERSION" packages/raise-cli/src/raise_cli/storage/schema.py

# Dev branch version (read from manifest)
DEV_BRANCH=$(python3 -c "import yaml; print(yaml.safe_load(open('.raise/manifest.yaml'))['branches']['development'])" 2>/dev/null || echo "release/3.1.0")
git show "origin/${DEV_BRANCH}:packages/raise-cli/src/raise_cli/storage/schema.py" | grep "^SCHEMA_VERSION"

If the two versions diverge (feature branch has V18, dev branch already at V19), assign migrations starting from max(both) + 1. Document the chosen version in the design. Skipping this check when branches diverge causes migration number collisions at merge time — a ~30 min fix that cannot be automated away.

Value preservation gate: Before finalizing components, ask: "What domain knowledge does this layer provide that a generic pass-through wouldn't?" If the answer is "none", the design may be over-abstracted. If the answer involves config/resolution/mapping that an existing pattern handles differently, check where that responsibility lives in the proven pattern.

Supply Chain Gate — For each NEW external dependency introduced by this story, evaluate supply chain health before committing:

• PyPI version history — stable releases? frequent yanks?
• Download count — established package or niche?
• Last release date — actively maintained?
• Maintainer count — bus factor (single point of failure)?
• Yank history — has this package had yanked versions in the past?
• Alternative evaluation — can we implement this ourselves in <50 LOC? Is there a lighter alternative?
• Isolation strategy — is the dependency confined to a single module, or does it leak across the codebase?

Document findings in the design doc's Approach section. This is a guide, not a hard block — an informed risk decision is valid.

Skip rule: Well-known, widely-adopted packages (pydantic, fastapi, pytest, requests, httpx, typer, rich, click, and similar) are N/A — their supply chain health is already established. Use human judgment for the boundary.

See pattern BASE-056: Consumer reputation ≠ package stability — verify supply chain independently (will be registered in RAISE-586).

For complex stories, add: scenarios (Gherkin), algorithm pseudocode, constraints, testing strategy.

Step 5: Create Examples (MOST IMPORTANT)

This section drives AI code generation accuracy more than any other.

Provide concrete, runnable examples:

1. API/CLI usage — how the story is invoked
2. Expected output — success + error cases
3. Data structures — key models, schemas, types

Use concrete values (not placeholders), correct syntax (not pseudocode), consistent with codebase style.

Step 6: Define Acceptance Criteria

JIT: Before defining acceptance criteria, query graph for testing patterns and quality standards → aspects/introspection.md § JIT Protocol

If story.md has Gherkin AC, reference them here — refine, don't duplicate. If no story.md, define from scratch:

• MUST: Required for completion (3-5 items, specific and testable)
• SHOULD: Nice-to-have (1-3 items)
• MUST NOT: Explicit anti-requirements

All criteria must be observable outcomes traceable to value from Step 2.

Output

After completing all steps, persist the design to the artifact store and render a Markdown view:

1. Emit structured artifact (primary — canonical source)

Call raise_artifact_emit with the design content as structured JSON. The artifact store is the source of truth.

raise_artifact_emit(
    artifact_type="design",
    story_id="{story_id}",
    content=<JSON string with fields: problem, value, approach, components, decisions,
             acceptance_criteria, examples, complexity, dependencies, legacy_sweep,
             drift_risks, testing_strategy, open_questions>
             cwd="{project_or_worktree_path}"
)

Field reference for the content JSON:

Note: The CLI fallback for artifact emission was removed in v3.0.0. MCP tool mcp__rai-workspace__raise_artifact_emit is required (primary path above). If MCP is unavailable, skip structured artifact emission.

2. Render Markdown view (derived — for human review)

Publish rendered Markdown via CLI for human readability, git diff, and Confluence:

Use raise_docs_write MCP tool with doc_type="story-design", title="S{N}.{M}: {story-name} design", content="[rendered Markdown from artifact store content]", output_path="work/epics/e{N}-{name}/stories/s{N}.{M}-design.md", cwd="{project_or_worktree_path}". Verify result: If result.status != "ok", stop immediately with error: Story design write failed: {result.error}. Cannot continue without docs sync in connected mode. If MCP tools are not available, fall back to:

rai docs write story-design \
  --title "S{N}.{M}: {story-name} design" \
  --stdin \
  --output-path work/epics/e{N}-{name}/stories/s{N}.{M}-design.md << 'EOF'
[rendered Markdown from artifact store content]
EOF

If exit code != 0, stop immediately — do not proceed.

The Markdown file is a rendered view, not the source of truth. It is generated from the artifact content. If the artifact store and the file ever diverge, the artifact store wins.

3. Emit lifecycle signal

STOP HERE. Return your summary to the orchestrator. Do NOT invoke any further skill.

Quality Checklist

• NEVER over-specify HOW — trust AI for implementation details
• NEVER skip examples — they are the most important section
• Supply chain risk evaluated for new external dependencies (or N/A)

References

• Next: /rai-story-plan
• Risk assessment: design is not optional
• UX research gate: /rai-research before UX stories
• Value preservation gate: domain intelligence over abstraction