raise-cli 2.2.1__py3-none-any.whl

raise_cli/skills_base/rai-epic-design/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: rai-epic-design
+description: >
+  Design an epic from strategic objective to feature breakdown. Use when
+  starting a new body of work spanning multiple features (3-10), requiring
+  architectural decisions, or when establishing technical direction for
+  significant capability delivery.
+
+license: MIT
+
+metadata:
+  raise.work_cycle: epic
+  raise.frequency: per-epic
+  raise.fase: "3"
+  raise.prerequisites: project-backlog
+  raise.next: epic-plan
+  raise.gate: ""
+  raise.adaptable: "true"
+  raise.version: "2.1.0"
+  raise.visibility: public
+  raise.inputs: |
+    - brief: file_path, optional, previous_skill
+    - scope: file_path, required, previous_skill
+  raise.outputs: |
+    - scope: file_path, next_skill
+    - design: file_path, optional, next_skill
+---
+
+# Epic Design
+
+## Purpose
+
+Design an epic that bridges strategic objectives to executable stories, making key architectural decisions and defining bounded scope for incremental delivery.
+
+## Mastery Levels (ShuHaRi)
+
+- **Shu**: Follow all steps, create full scope document and ADRs
+- **Ha/Ri**: Adjust depth based on complexity, lightweight ADRs, custom patterns
+
+## Context
+
+**When to use:** Starting work spanning 3-10 stories, requiring architectural decisions, or establishing technical direction.
+
+**When to skip:** Single-story work → `/rai-story-design`. Bug fixes → issue tracker. High uncertainty → `/rai-research` first.
+
+**Inputs:** Business objective, project backlog, constraints. Optionally: Problem Brief from `/rai-problem-shape` or Epic Brief from `/rai-epic-start`.
+
+## Steps
+
+### Step 1: Load Brief & Frame Objective
+
+Check for Epic Brief (`work/epics/e{N}-{name}/brief.md`) or Problem Brief (`work/problem-briefs/*.md`). If found, use hypothesis and boundaries as starting input.
+
+Define what this epic accomplishes:
+- **Objective**: Business/user outcome (1-2 sentences, outcome-focused)
+- **Value**: Why this matters, what's unlocked after completion
+- **In scope (MUST/SHOULD)**: Non-negotiable vs nice-to-have deliverables
+- **Out of scope**: Excluded items with rationale and deferral destination
+
+Scoping heuristic: defer what doesn't block the objective; separate what needs its own ADRs.
+
+<verification>
+Objective explainable to non-technical stakeholder in 60 seconds. Scope boundaries explicit.
+</verification>
+
+### Step 2: Assess Architecture & ADRs
+
+```bash
+rai graph context mod-<name>
+```
+
+Create ADRs when: multiple valid approaches with significant impact, new technology adoption, decisions other epics depend on. Skip when patterns are established or details are easily changed.
+
+If significant uncertainty: `/rai-research` (timebox 2-4 hours), then create ADRs.
+ADR template: `.raise/templates/architecture/adr.md`. One decision per ADR.
+
+<verification>
+Technical direction clear enough to define stories. ADRs created for significant decisions.
+</verification>
+
+### Step 3: Break Down Stories
+
+Decompose epic into 3-10 independently deliverable stories.
+
+**Per story:** ID (S{N}.{seq}), name, 1-line description, T-shirt size (XS/S/M/L), dependencies.
+
+Target: each story delivers demonstrable value, 1-5 days duration. No dependency cycles. External blockers identified.
+
+<verification>
+Each story passes "independently deliverable" test. Dependency graph is acyclic.
+</verification>
+
+### Step 4: Define Done & Risks
+
+**Done:** All stories complete + epic-specific measurable criteria + architecture docs updated + retrospective completed.
+
+**Risks:** Top 3 with likelihood/impact/mitigation.
+
+<verification>
+Done criteria are measurable. Top risks have mitigations.
+</verification>
+
+### Step 5: Write Artifacts & Parking Lot
+
+Create TWO documents using templates:
+1. `scope.md` (WHAT + WHY): objective, stories, boundaries, done criteria → `templates/scope.md`
+2. `design.md` (HOW): Gemba, target components, key contracts → `templates/design.md`
+
+For simple epics (no architecture changes), `design.md` is optional.
+
+Capture deferred items in `dev/parking-lot.md` with origin, priority, and promotion conditions.
+
+<verification>
+Scope document reviewable in <10 minutes. Parking lot updated.
+</verification>
+
+## Output
+
+| Item | Destination |
+|------|-------------|
+| Scope document | `work/epics/e{N}-{name}/scope.md` |
+| Design document | `work/epics/e{N}-{name}/design.md` (if architecture) |
+| ADRs | `dev/decisions/adr-*.md` (0-3 typical) |
+| Parking lot | `dev/parking-lot.md` |
+| Next | `/rai-epic-plan` |
+
+## Quality Checklist
+
+- [ ] Epic Brief consumed as input (if exists from `/rai-epic-start`)
+- [ ] Objective is outcome-focused, not implementation-focused
+- [ ] Scope boundaries explicit (in/out documented)
+- [ ] Stories independently deliverable (3-10 range)
+- [ ] Dependencies mapped with no cycles
+- [ ] Done criteria are measurable
+- [ ] NEVER time-box epics — scope-based, not duration-based
+- [ ] NEVER over-specify stories — save details for `/rai-story-design`
+
+## References
+
+- Brief template: `rai-epic-start/templates/brief.md`
+- Scope template: `templates/scope.md`
+- Design template: `templates/design.md`
+- ADR template: `.raise/templates/architecture/adr.md`
+- Next: `/rai-epic-plan`
+- Story design: `/rai-story-design`
+- Close: `/rai-epic-close`

raise_cli/skills_base/rai-epic-design/templates/design.md

@@ -0,0 +1,24 @@
+---
+epic_id: "{EPIC_ID}"
+grounded_in: "Gemba of [files read]"
+---
+
+# Epic Design: {title}
+
+## Affected Surface (Gemba)
+
+| Module/File | Current State | Changes |
+|-------------|---------------|---------|
+| [path] | [what exists] | [what changes] |
+
+## Target Components
+
+| Component | Responsibility | Key Interface |
+|-----------|---------------|---------------|
+| [name] | [what it does] | [public API] |
+
+## Key Contracts
+[Types and interfaces at component level — actual signatures, not pseudocode]
+
+## Migration Path
+[Backward compat strategy, consumer changes needed. Omit if greenfield.]

raise_cli/skills_base/rai-epic-design/templates/scope.md

@@ -0,0 +1,76 @@
+# Epic E{N}: {Epic Name} — Scope
+
+> **Status:** IN PROGRESS
+> **Release:** REL-{id} ({release name})
+> **Created:** YYYY-MM-DD
+
+## Objective
+
+{1-2 sentences: What business/user outcome does this epic deliver?}
+
+**Value:** {Why this matters, what's unlocked after completion}
+
+## Stories ({X} SP estimated)
+
+| ID | Story | Size | Status | Description |
+|----|-------|:----:|:------:|-------------|
+| S{N}.1 | {Name} | S | Pending | {1-line} |
+| S{N}.2 | {Name} | M | Pending | {1-line} |
+
+**Total:** {X} stories, {Y} SP
+
+## Scope
+
+**In scope (MUST):**
+- {Non-negotiable 1}
+- {Non-negotiable 2}
+
+**In scope (SHOULD):**
+- {Nice-to-have 1}
+
+**Out of scope:**
+- {Excluded 1} → {where deferred}
+
+## Done Criteria
+
+**Per story:**
+- [ ] Code with type annotations
+- [ ] Tests passing
+- [ ] Quality checks pass (ruff, pyright)
+
+**Epic complete:**
+- [ ] All stories complete (S{N}.1–S{N}.X)
+- [ ] {Epic-specific criterion 1}
+- [ ] Epic retrospective done
+- [ ] Merged to `{dev_branch}`
+
+## Dependencies
+
+```
+S{N}.1 (foundation)
+  ↓
+S{N}.2 ──┐
+  ↓      │ (parallel)
+S{N}.3 ◄─┘
+```
+
+**External:** {None / list}
+
+## Architecture
+
+| Decision | ADR | Summary |
+|----------|-----|---------|
+| {Decision 1} | ADR-{XXX} | {1-line} |
+
+> Problem Brief: {path or "N/A"}
+
+## Risks
+
+| Risk | L/I | Mitigation |
+|------|:---:|------------|
+| {Risk 1} | H/M | {strategy} |
+| {Risk 2} | M/L | {strategy} |
+
+## Parking Lot
+
+- {Deferred item} → {destination}

raise_cli/skills_base/rai-epic-plan/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: rai-epic-plan
+description: >
+  Sequence features from epic-design into an executable plan with milestones,
+  dependencies, and progress tracking. Use after /rai-epic-design to create a
+  realistic implementation roadmap before starting story work.
+
+license: MIT
+
+metadata:
+  raise.work_cycle: epic
+  raise.frequency: per-epic
+  raise.fase: "4"
+  raise.prerequisites: epic-design
+  raise.next: story-start
+  raise.gate: ""
+  raise.adaptable: "true"
+  raise.version: "2.2.0"
+  raise.visibility: public
+  raise.inputs: |
+    - scope: file_path, required, previous_skill
+  raise.outputs: |
+    - scope: file_path, next_skill
+---
+
+# Epic Plan
+
+## Purpose
+
+Transform the story list from `/rai-epic-design` into a sequenced implementation plan with milestones, parallel work streams, and progress tracking.
+
+## Mastery Levels (ShuHaRi)
+
+- **Shu**: Follow all steps, create sequenced plan with walking skeleton + MVP milestones
+- **Ha**: Adjust milestone granularity based on epic size, skip timeline for small epics
+- **Ri**: Domain-specific sequencing patterns, team velocity models
+
+## Context
+
+**When to use:** After `/rai-epic-design` has produced a scope document with stories. Before starting first story.
+
+**When to skip:** Very small epics (2-3 stories) with obvious linear sequence. Emergency fixes.
+
+**Inputs:** Epic scope document (`work/epics/e{N}-{name}/scope.md`), calibration data (if available).
+
+## Steps
+
+### Step 1: Review Epic Scope
+
+Load and understand the epic scope document:
+- Story list with sizes and dependencies
+- Done criteria and risks
+- Architectural decisions that affect sequencing
+
+<verification>
+Can explain epic scope and story dependencies in 60 seconds.
+</verification>
+
+<if-blocked>
+Epic design incomplete → run `/rai-epic-design` first.
+</if-blocked>
+
+### Step 2: Sequence & Rationalize
+
+Order stories using these strategies (in priority order):
+
+| Strategy | When | Rationale |
+|----------|------|-----------|
+| **Risk-first** | High uncertainty features | Tackle unknowns early while energy is high and time for pivots remains |
+| **Walking skeleton** | Architecture unproven | Build minimal E2E path first to prove architecture |
+| **Quick wins** | Need momentum | Early deliverable value, validate tooling |
+| **Dependency-driven** | Hard blockers exist | Unblock others on critical path |
+
+For each story, document: position, rationale, dependencies (hard/soft/external), what it enables.
+
+**Identify parallel opportunities:** Stories with no mutual dependencies, different codebase areas, or independent concerns can run concurrently.
+
+<verification>
+Every story has sequencing rationale. Critical path identified. Parallel opportunities documented.
+</verification>
+
+### Step 3: Define Milestones
+
+Create 2-4 intermediate checkpoints:
+
+| Milestone | Typical scope | Purpose |
+|-----------|---------------|---------|
+| **M1: Walking Skeleton** | 1-3 stories (smallest E2E) | Prove architecture, enable integration |
+| **M2: Core MVP** | 50-70% of stories | Demonstrate value, gather feedback |
+| **M3: Feature Complete** | 100% planned stories | Ready for polish |
+| **M4: Epic Complete** | Done criteria met | Ready for `/rai-epic-close` |
+
+Per milestone: stories included, success criteria (verifiable), demo capability.
+
+**Integration checkpoint (PAT-E-539):** For epics with multiple components (client/server, CLI/API, frontend/backend), schedule an **E2E integration milestone** before the final story. This checkpoint runs real infrastructure (docker compose, actual DB) and verifies cross-story contracts (auth headers, payload schemas, parameter limits). Unit tests with mocks cannot catch these mismatches — only real E2E validates the seams between stories.
+
+<verification>
+At least 2 milestones defined with clear success criteria. Multi-component epics include E2E integration checkpoint.
+</verification>
+
+### Step 4: Setup Tracking
+
+Add progress tracking to epic scope using `templates/plan-section.md`:
+- Story sequence table with status/actual/velocity columns
+- Milestone checklist with target dates
+- Velocity assumptions from calibration data (if available)
+
+<verification>
+Tracking table added to epic scope document.
+</verification>
+
+### Step 5: Update Scope Document
+
+Append the implementation plan section to `work/epics/e{N}-{name}/scope.md`. Include:
+- Story sequence with rationale
+- Milestones with success criteria
+- Parallel work streams (if any)
+- Progress tracking table
+- Sequencing risks (top 3)
+
+Present plan to human for review before starting first story.
+
+<verification>
+Scope document updated. Plan reviewable in <5 minutes. Human acknowledges.
+</verification>
+
+## Output
+
+| Item | Destination |
+|------|-------------|
+| Implementation plan | Appended to `work/epics/e{N}-{name}/scope.md` |
+| Plan template | `templates/plan-section.md` |
+| Next | `/rai-story-design` for first story in sequence |
+
+## Quality Checklist
+
+- [ ] All stories sequenced with rationale
+- [ ] Critical path identified
+- [ ] At least 2 milestones (walking skeleton + MVP minimum)
+- [ ] Dependencies verified — no cycles, blockers identified
+- [ ] Parallel opportunities documented (or explained why sequential)
+- [ ] Progress tracking in scope document
+- [ ] NEVER over-plan — plans are hypotheses, not commitments
+- [ ] NEVER sequence by size alone — use risk-first as default
+- [ ] Multi-component epics include E2E integration checkpoint (PAT-E-539)
+
+## References
+
+- Plan template: `templates/plan-section.md`
+- Previous: `/rai-epic-design` (produces scope input)
+- Next: `/rai-story-design` for first story
+- Close: `/rai-epic-close`
+- Calibration: `.raise/rai/memory/calibration.jsonl`

raise_cli/skills_base/rai-epic-plan/_references/sequencing-strategies.md

@@ -0,0 +1,67 @@
+# Sequencing Strategies Deep Dive
+
+> Reference material for `/rai-epic-plan` Step 3.
+> For quick reference, see the decision matrix in the main skill.
+
+---
+
+## Risk-First (Primary Strategy)
+
+**Philosophy:** Uncertainty decreases as you learn. Early features teach you about the codebase, the problem, and your velocity. Tackling risky features early means:
+- More time to recover from surprises
+- Learning informs later features
+- Confidence grows throughout epic
+
+**Identify risky features by:**
+- New technology or unfamiliar patterns
+- Integration with external systems
+- Unclear requirements (even after design)
+- Performance or scalability unknowns
+- Team has never done something similar
+
+**Anti-pattern:** "Let's do the easy features first to build momentum" — This feels good but front-loads certainty and back-loads risk. By the time you hit the hard features, deadline pressure is highest.
+
+---
+
+## Walking Skeleton
+
+**Philosophy:** Prove the architecture works before investing heavily. A walking skeleton is the smallest end-to-end path through the system that demonstrates:
+- Key architectural decisions are valid
+- Integration points work
+- Development environment is productive
+- Deployment pipeline functions
+
+**Walking skeleton features:**
+- Minimal but complete path from input to output
+- Touches all layers (UI, API, data, infrastructure)
+- Can be demonstrated (not just "it compiles")
+- Provides foundation for rest of features
+
+**Example:** For a governance toolkit epic, walking skeleton might be:
+- F1: Extract one concept from one file
+- F2: Build minimal graph with one relationship
+- F3: Query graph and return result
+
+**Anti-pattern:** Building all of layer 1 before touching layer 2. This delays integration risk discovery.
+
+---
+
+## Quick Wins
+
+**Philosophy:** Early success builds momentum and validates process. Quick wins are features that:
+- Can be completed in one session
+- Provide visible, demonstrable value
+- Don't block other features
+- Build confidence in approach
+
+**Use quick wins when:**
+- Starting a new codebase or technology
+- Team morale needs boost
+- Stakeholders need early visibility
+- Validating development process
+
+**Anti-pattern:** Only quick wins — avoiding hard features indefinitely. Quick wins support risk-first; they don't replace it.
+
+---
+
+*Reference document for /rai-epic-plan*

raise_cli/skills_base/rai-epic-plan/templates/plan-section.md

@@ -0,0 +1,49 @@
+## Implementation Plan
+
+> Added by `/rai-epic-plan` — YYYY-MM-DD
+
+### Story Sequence
+
+| Order | Story | Size | Dependencies | Milestone | Rationale |
+|:-----:|-------|:----:|--------------|-----------|-----------|
+| 1 | S{N}.1 | S | None | M1 | {Why first?} |
+| 2 | S{N}.2 | M | S{N}.1 | M1 | {Why second?} |
+| 3 | S{N}.3 | S | S{N}.2 | M2 | {Why here?} |
+
+### Milestones
+
+| Milestone | Stories | Target | Success Criteria |
+|-----------|---------|--------|------------------|
+| **M1: Walking Skeleton** | S{N}.1, S{N}.2 | {Day} | {What proves it works?} |
+| **M2: Core MVP** | +S{N}.3, S{N}.4 | {Day} | {What proves value?} |
+| **M3: Feature Complete** | +S{N}.5... | {Day} | All planned stories done |
+| **M4: Epic Complete** | — | {Day} | Done criteria met, retro done |
+
+### Parallel Work Streams
+
+```
+Time →
+Stream 1 (Critical): S{N}.1 ─► S{N}.2 ─► S{N}.5
+                              ↓
+Stream 2 (Parallel):        S{N}.3 ─► merge
+                                       ↑
+Stream 3 (Parallel):        S{N}.4 ───┘
+```
+
+**Merge points:**
+- After S{N}.1: split into parallel streams
+- Before S{N}.5: merge parallel streams
+
+### Progress Tracking
+
+| Story | Size | Status | Actual | Velocity | Notes |
+|-------|:----:|:------:|:------:|:--------:|-------|
+| S{N}.1 | S | Pending | — | — | |
+| S{N}.2 | M | Pending | — | — | |
+
+### Sequencing Risks
+
+| Risk | L/I | Mitigation |
+|------|:---:|------------|
+| {Risk 1} | H/M | {Strategy} |
+| {Risk 2} | M/L | {Strategy} |