raise-cli 2.2.1__py3-none-any.whl

raise_cli/skills_base/rai-story-review/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: rai-story-review
+description: >
+  Reflect on completed stories to extract learnings, identify process
+  improvements, and update the framework with insights gained. Use after
+  implementation is complete to close the development cycle.
+
+license: MIT
+
+metadata:
+  raise.work_cycle: story
+  raise.frequency: per-story
+  raise.fase: "7"
+  raise.prerequisites: story-implement
+  raise.next: story-close
+  raise.gate: ""
+  raise.adaptable: "true"
+  raise.version: "2.2.0"
+  raise.visibility: public
+  raise.inputs: |
+    - tests_passing: boolean, required, cli
+  raise.outputs: |
+    - retrospective_md: file_path, next_skill
+    - patterns: list, cli
+---
+
+# Story Review
+
+## Purpose
+
+Reflect on the completed story to extract learnings, persist patterns, reinforce behavioral signals, and emit calibration telemetry.
+
+## Mastery Levels (ShuHaRi)
+
+- **Shu**: Follow all steps, answer all checkpoint questions with specific examples
+- **Ha**: Adapt depth to story complexity, batch small story reviews
+- **Ri**: Custom review patterns, integrate with team retrospectives
+
+## Context
+
+**When to use:** After implementation is complete and tests pass. Before `/rai-story-close`.
+
+**Inputs:** Completed story, progress log, passing test suite.
+
+## Steps
+
+### Step 1: Verify Tests Pass
+
+Determine which test command to run using this priority chain:
+
+1. **Check `.raise/manifest.yaml`** for `project.test_command` — if set, use it directly (configuration over convention)
+2. **Detect language** from `project.project_type` in manifest, or scan file extensions of changed files (`git diff --name-only`)
+3. **Map language to default** using the table below
+
+```yaml
+# .raise/manifest.yaml — example
+project:
+  test_command: "cargo test --quiet"   # explicit override, highest priority
+  project_type: rust
+```
+
+| Language | Extensions | Default Test Command |
+|----------|-----------|----------------------|
+| Python | `.py`, `.pyi` | `uv run pytest --tb=short` |
+| TypeScript | `.ts`, `.tsx` | `npx vitest run` or `npm test` |
+| JavaScript | `.js`, `.jsx` | `npx vitest run` or `npm test` |
+| C# | `.cs` | `dotnet test --verbosity quiet` |
+| Go | `.go` | `go test ./...` |
+| PHP | `.php` | `vendor/bin/phpunit` |
+| Dart | `.dart` | `flutter test` |
+| Unknown | — | Ask developer |
+
+The table is a **fallback** — `project.test_command` always wins when present.
+
+| Condition | Action |
+|-----------|--------|
+| Tests green | Continue |
+| Tests failing | Fix first — review requires green tests |
+
+<verification>
+Project language detected. Tests passing with appropriate runner.
+</verification>
+
+### Step 2: Gather Data & Reflect
+
+Review the story development: actual vs estimated time, blockers, plan deviations.
+
+**Heutagogical checkpoint** — answer with specific examples:
+1. What did you learn?
+2. What would you change about the process?
+3. Are there improvements for the framework?
+4. What are you more capable of now?
+
+Identify concrete improvements to skills, guardrails, or templates. Apply small improvements immediately; create issues for complex ones.
+
+<verification>
+All four questions answered. Improvements identified (or celebrated that none needed).
+</verification>
+
+### Step 3: Persist Patterns & Reinforce
+
+**Add new patterns** worth preserving across sessions:
+
+```bash
+rai pattern add "Pattern description" -c "context,keywords" -t process --from S{N}.{M}
+```
+
+Types: `process`, `technical`, `architecture`, `codebase`.
+
+**Reinforce existing patterns** — evaluate behavioral patterns loaded at session start:
+
+```bash
+rai pattern reinforce {pattern_id} --vote {1|0|-1} --from S{N}.{M}
+```
+
+| Vote | Meaning |
+|:----:|---------|
+| `1` | Implementation followed the pattern |
+| `0` | Pattern not relevant to this story (does NOT count toward evaluations) |
+| `-1` | Implementation contradicted the pattern |
+
+Only evaluate patterns you consciously considered. `0` is correct for most patterns in any story.
+
+<verification>
+New patterns persisted. Behavioral patterns evaluated (or explicitly skipped).
+</verification>
+
+### Step 4: Document Retrospective
+
+Create `work/epics/e{N}-{name}/stories/s{N}.{M}-retrospective.md` with:
+- Summary (story ID, dates, estimated vs actual time)
+- What went well / what to improve
+- Heutagogical checkpoint answers
+- Improvements applied
+- Patterns added/reinforced
+
+<verification>
+Retrospective document created.
+</verification>
+
+### Step 5: Emit Calibration Telemetry
+
+```bash
+rai signal emit-calibration S{N}.{M} --size {XS|S|M|L} --estimated {minutes} --actual {minutes}
+```
+
+This feeds the velocity tracking system for future estimation accuracy.
+
+<verification>
+Calibration event recorded (or skipped if CLI unavailable).
+</verification>
+
+## Output
+
+| Item | Destination |
+|------|-------------|
+| Retrospective | `work/epics/e{N}-{name}/stories/s{N}.{M}-retrospective.md` |
+| Patterns | `.raise/rai/memory/patterns.jsonl` |
+| Calibration | Via `rai signal emit-calibration` |
+| Next | `/rai-story-close` |
+
+## Quality Checklist
+
+- [ ] Project language detected before running tests
+- [ ] Tests pass with language-appropriate runner (gate)
+- [ ] Heutagogical checkpoint answered with specific examples
+- [ ] New patterns persisted via `rai pattern add`
+- [ ] Behavioral patterns reinforced via `rai pattern reinforce`
+- [ ] Calibration telemetry emitted
+- [ ] Retrospective document created
+- [ ] NEVER skip pattern reinforce — scoring system depends on it (RAISE-170)
+- [ ] NEVER give vague checkpoint answers — be specific with concrete examples
+
+## References
+
+- Previous: `/rai-story-implement`
+- Next: `/rai-story-close`
+- Pattern scoring: RAISE-170 (temporal decay + Wilson scorer)

raise_cli/skills_base/rai-story-run/SKILL.md

@@ -0,0 +1,282 @@
+---
+name: rai-story-run
+description: >
+  Chain the full story lifecycle (start → design → plan → implement →
+  architecture review → quality review → review → close) in one
+  invocation. Resumes from last completed phase using git-derived
+  artifact detection. Delegation profile controls pause behavior.
+
+license: MIT
+
+metadata:
+  raise.work_cycle: story
+  raise.frequency: per-story
+  raise.fase: ""
+  raise.prerequisites: ""
+  raise.next: ""
+  raise.gate: ""
+  raise.adaptable: "true"
+  raise.version: "2.0.0"
+  raise.visibility: public
+  raise.inputs: |
+    - story_id: string, required, argument (e.g. "S325.6")
+    - epic_id: string, optional, argument (inferred from story_id prefix)
+  raise.outputs: |
+    - merge_commit: string, git
+    - retrospective_md: file_path (work/epics/.../stories/s{N}.{M}-retrospective.md)
+    - patterns: list, cli (via rai pattern add)
+---
+
+# Story Run
+
+## Purpose
+
+Execute the full story lifecycle in one invocation, pausing only at delegation gates and resuming automatically from the last completed phase.
+
+## Mastery Levels (ShuHaRi)
+
+- **Shu**: Show phase progress, explain each skill's output, pause at both gates
+- **Ha**: Brief progress between phases, pause only when delegation says REVIEW
+- **Ri**: Minimal output, AUTO delegation, gates stop only on failure
+
+## Context
+
+**When to use:** Starting or resuming any story. Replaces manual sequential skill invocation.
+
+**When to skip:** Single-phase work (e.g., only running review on an already-implemented story). Individual skills remain independently invocable.
+
+## Steps
+
+### Step 0: Detect Phase
+
+Resolve the epic and story paths from `story_id`. Check artifacts in **reverse order** — take the most advanced phase:
+
+| Check | Artifact | If exists → resume at |
+|:-----:|----------|----------------------|
+| 5 | `stories/s{N}.{M}-retrospective.md` | **close** |
+| 4 | `stories/s{N}.{M}-plan.md` | **implement** |
+| 3 | `stories/s{N}.{M}-design.md` | **plan** |
+| 2 | `stories/s{N}.{M}-story.md` | **design** |
+| 1 | story branch exists (`story/s{N}.{M}/*`) | **start** (branch only, no artifacts) |
+| 0 | (nothing) | **start** (from scratch) |
+
+Present: "Phase detection: resuming at **{phase}** (found: {artifact})" or "Starting fresh — no artifacts found."
+
+<verification>
+Phase identified. Epic path resolved.
+</verification>
+
+### Step 1: Resolve Delegation
+
+Load developer profile from `~/.rai/developer.yaml`. Resolve delegation level:
+
+| Source | Resolution |
+|--------|-----------|
+| `delegation.overrides.rai-story-run` | Per-skill override (highest priority) |
+| `delegation.default_level` | Explicit default |
+| `experience_level` ShuHaRi | Shu→REVIEW, Ha→NOTIFY, Ri→AUTO |
+| No profile | Default to REVIEW |
+
+Present: "Delegation: **{level}**"
+
+<verification>
+Delegation level resolved.
+</verification>
+
+### Step 2: Execute Skill Chain
+
+Run each skill from the detected phase forward.
+
+**Phase banner (before starting):**
+
+```
+── Phase {N}/8: {skill_name} ──
+```
+
+**Completion banner (after finishing each phase):**
+
+Use a markdown heading + table so that file paths are clickable in the terminal:
+
+```markdown
+### ✔ Phase {N}/8 — {skill_name}
+
+| | File | Status |
+|---|---|---|
+| + | `path/to/new-file.md` | created |
+| ~ | `path/to/modified-file.py` | modified |
+
+**Commits:** 1 (`abc1234`) · **Tests:** 3463 passed
+```
+
+Rules for the completion banner:
+- Use markdown table (NOT ASCII box-drawing) so file paths are clickable
+- File paths in backticks, relative to project root
+- `+` for created, `~` for modified, `-` for deleted
+- Only list files the skill actually touched (not inherited from prior phases)
+- Commits and tests on a single summary line below the table
+- For gate phases (design, implement, AR, QR), add verdict/summary on a separate line
+- If phase produced no file changes (e.g., close is just merge), show merge commit hash instead of file table
+
+**Chain order:**
+
+| Phase | Skill | Execution | Gate after? |
+|:-----:|-------|:---------:|:-----------:|
+| 1 | `/rai-story-start {story_id}` | **fork** | — |
+| 2 | `/rai-story-design {story_id}` | **fork** | POST-DESIGN |
+| 3 | `/rai-story-plan {story_id}` | **fork** | — |
+| 4 | `/rai-story-implement {story_id}` | **fork** | POST-IMPLEMENT |
+| 5 | `/rai-architecture-review {story_id} story` | **fork** | POST-AR |
+| 6 | `/rai-quality-review {story_id}` | **fork** | POST-QR |
+| 7 | `/rai-story-review {story_id}` | **fork** | — |
+| 8 | `/rai-story-close {story_id}` | **fork** | — |
+
+**All phases fork.** The orchestrator is a pure coordinator — it never executes skill logic directly. This keeps the terminal output clean (subagent output is contained) and the orchestrator context minimal.
+
+#### Fork phases (all 8)
+
+Each fork phase runs in a **fresh-context subagent** via the Agent tool. This eliminates context saturation that degrades quality in later phases.
+
+**For each fork phase:**
+
+1. **Read** the skill's SKILL.md from `src/raise_cli/skills_base/rai-{skill-name}/SKILL.md`
+2. **Spawn** an Agent tool subagent with:
+   - `subagent_type: "general-purpose"`
+   - `prompt`: the agent prompt template below, filled with skill content and story context
+3. **Wait** for agent completion
+4. **Verify** output:
+   - Artifact-producing phases (start, design, plan, implement, review): confirm file exists on disk
+   - Verdict phases (AR, QR): read verdict from agent return value
+   - Close: confirm merge commit from agent return value
+5. **Show** completion banner in main thread
+6. **Apply** delegation gate if applicable (in main thread)
+
+**Agent prompt template:**
+
+```
+Execute the following skill for story {story_id}.
+
+## Skill Instructions
+
+{paste the full SKILL.md content here}
+
+## Story Context
+
+- Story ID: {story_id}
+- Epic: {epic_id}
+- Epic path: work/epics/{epic_slug}/
+- Stories path: work/epics/{epic_slug}/stories/
+- Prior artifacts on disk: {list each file that exists for this story, e.g. s353.2-story.md, s353.2-design.md}
+
+## Your Task
+
+1. Read CLAUDE.md for project-level context and rules
+2. Read the prior artifacts listed above from disk
+3. Execute every step in the Skill Instructions — no compression, no skipping
+4. Write all output artifacts to the correct paths
+5. When done, return a brief summary: what you did, artifacts created, and any verdicts or decisions
+
+ARGUMENTS: {story_id}
+```
+
+**Critical rules for fork execution:**
+- The subagent gets the SKILL.md as its prompt — it executes the full skill naturally in fresh context
+- Do NOT pass conversation history or prior phase results to the subagent — only disk artifacts and SKILL.md
+- The orchestrator stays thin — it only reads summaries and checks for artifacts between forks
+- A skill invoked through fork must produce the same output as when invoked standalone
+
+<verification>
+Each skill's SKILL.md was loaded and all its steps executed before proceeding.
+</verification>
+
+<if-blocked>
+Skill fails → STOP immediately. Report which phase failed and why. The developer re-invokes `/rai-story-run` after fixing the issue — phase detection resumes from the last completed artifact.
+</if-blocked>
+
+### Step 3: Apply Delegation Gates
+
+After **phase 2 (design)**, **phase 4 (implement)**, **phase 5 (AR)**, and **phase 6 (QR)**, apply the delegation gate:
+
+| Level | Behavior |
+|-------|----------|
+| REVIEW | Present summary of completed phase. Wait for explicit approval before continuing. |
+| NOTIFY | Present summary. Continue after 3 seconds unless user intervenes. |
+| AUTO | Continue immediately. Gates still stop on test/lint/type failure or AR/QR SIMPLIFY/FAIL verdict. |
+
+**Post-design summary:** Approach, components affected, key decisions.
+**Post-implement summary:** Tasks completed, tests passing, files changed.
+**Post-AR summary:** Verdict (PASS/PASS WITH QUESTIONS/SIMPLIFY), findings count, key heuristics triggered.
+**Post-QR summary:** Verdict (PASS/PASS WITH RECOMMENDATIONS/FAIL), findings count, fixes applied.
+
+If AR verdict is SIMPLIFY or QR verdict is FAIL, STOP regardless of delegation level. Fixes must be applied before proceeding.
+
+<verification>
+Gate applied. Approval received (REVIEW) or notification shown (NOTIFY/AUTO).
+</verification>
+
+### Step 4: Complete & Report
+
+After all phases complete, present:
+
+```markdown
+## Story Run Complete: {story_id}
+
+**Phases:** {start_phase} → close ({N} phases executed)
+**Delegation:** {level}
+**Result:** Merged to `{parent_branch}` (`{merge_commit_hash}`)
+
+### Artifacts
+| Phase | File | Op |
+|-------|------|:--:|
+| start | `work/epics/.../stories/s{N}.{M}-story.md` | + |
+| start | `work/epics/.../stories/s{N}.{M}-scope.md` | + |
+| design | `work/epics/.../stories/s{N}.{M}-design.md` | + |
+| plan | `work/epics/.../stories/s{N}.{M}-plan.md` | + |
+| implement | `src/path/to/file.py` | ~ |
+| implement | `tests/path/to/test.py` | ~ |
+| review | `work/epics/.../stories/s{N}.{M}-retrospective.md` | + |
+
+### Metrics
+| Metric | Value |
+|--------|-------|
+| Tests | {count} passed |
+| Commits | {total_count} across {phases_count} phases |
+| Patterns | {PAT-IDs or "none"} |
+| Jira | {ticket} → {status} |
+```
+
+File paths MUST use backticks so they are clickable in the terminal. Use actual paths, not placeholders — the table above is a template.
+
+<verification>
+All phases complete. Story merged and branch cleaned up.
+</verification>
+
+## Output
+
+| Item | Destination |
+|------|-------------|
+| All story artifacts | `work/epics/e{N}-{name}/stories/` |
+| Merge commit | Parent branch (epic or dev) |
+| Patterns | `.raise/rai/memory/patterns.jsonl` |
+| Calibration | Via `rai signal emit-calibration` |
+| Next | Next story or `/rai-epic-close` |
+
+## Quality Checklist
+
+- [ ] Phase detection checked in reverse order (most advanced first)
+- [ ] Delegation resolved from profile before starting chain
+- [ ] All 8 phases spawn Agent tool subagent with full SKILL.md as prompt
+- [ ] Each subagent gets fresh context — no conversation history passed
+- [ ] Artifact-producing forks verified by checking file on disk
+- [ ] AR/QR verdicts read from agent return value
+- [ ] Gates applied at post-design, post-implement, post-AR, and post-QR (in main thread)
+- [ ] Failure stops immediately — no cascading to next phase
+- [ ] NEVER create a state file — phase detection is git-derived only
+- [ ] NEVER skip a skill in the chain (even if developer says "just close it")
+- [ ] NEVER pass conversation context to forked subagent — only disk artifacts + SKILL.md
+
+## References
+
+- Skills: `/rai-story-start`, `/rai-story-design`, `/rai-story-plan`, `/rai-story-implement`, `/rai-architecture-review`, `/rai-quality-review`, `/rai-story-review`, `/rai-story-close`
+- Delegation: `~/.rai/developer.yaml`, S325.2
+- BacklogHook: S325.4 (fires on `rai signal emit-work` in start/close)
+- Design: `s325.6-design.md` (decisions D1-D2-D3)

raise_cli/skills_base/rai-story-start/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: rai-story-start
+description: >
+  Initialize a story with verified context, branch, and scope commit.
+  Use at the beginning of story work to ensure proper setup and
+  traceability from the start.
+
+license: MIT
+
+metadata:
+  raise.work_cycle: story
+  raise.frequency: per-story
+  raise.fase: "3"
+  raise.prerequisites: ""
+  raise.next: story-design
+  raise.gate: ""
+  raise.adaptable: "true"
+  raise.version: "3.0.0"
+  raise.visibility: public
+  raise.inputs: |
+    - story_id: string, required, argument
+    - dev_branch: string, required, config
+  raise.outputs: |
+    - story_branch: string, next_skill
+    - story_md: file_path, next_skill
+    - scope_md: file_path, next_skill
+---
+
+# Story Start
+
+## Purpose
+
+Initialize a story with a dedicated branch from the development branch and a scope commit that documents boundaries and done criteria.
+
+## Mastery Levels (ShuHaRi)
+
+- **Shu**: Follow all steps, verify epic context, create branch with scope commit
+- **Ha**: Skip epic verification for standalone stories or experiments
+- **Ri**: Custom initialization patterns for specific workflows
+
+## Context
+
+**When to use:** Starting a new story from the backlog or epic scope.
+
+**When to skip:** Quick bug fixes (direct branch). Continuation of already-started story.
+
+**Inputs:** Story ID (S{N}.{M}), epic scope document (if part of an epic), clear understanding of story scope.
+
+**Branch config:** Read `branches.development` from `.raise/manifest.yaml` for `{dev_branch}`. Default: `main`.
+
+## Steps
+
+### Step 1: Verify Epic Context (if applicable)
+
+If this story belongs to an epic, verify the epic directory and scope exist:
+
+```bash
+ls work/epics/e{N}-{name}/scope.md
+```
+
+| Condition | Action |
+|-----------|--------|
+| Epic scope exists | Continue — verify story is listed in scope |
+| Epic scope missing | Run `/rai-epic-start` first |
+| Standalone story | No epic verification needed |
+
+<verification>
+Epic context verified (or documented as standalone).
+</verification>
+
+### Step 2: Create Story Branch from Dev
+
+Always branch from `{dev_branch}`:
+
+```bash
+git checkout {dev_branch} && git pull origin {dev_branch}
+git checkout -b story/s{N}.{M}/{story-slug}
+```
+
+| Condition | Action |
+|-----------|--------|
+| M/L story | Create dedicated `story/` branch |
+| S/XS story | Create branch anyway — all stories branch from `{dev_branch}` |
+| Standalone | Same — `story/s{N}.{M}/{slug}` from `{dev_branch}` |
+
+<verification>
+On story branch created from `{dev_branch}`.
+</verification>
+
+### Step 3: Define Scope & Commit
+
+Create TWO artifacts:
+
+1. `work/epics/e{N}-{name}/stories/s{N}.{M}-story.md` using `templates/story.md` — user story (Connextra), Gherkin AC, SbE examples. For XS stories, informal AC is acceptable.
+2. `work/epics/e{N}-{name}/stories/s{N}.{M}-scope.md` — in scope/out of scope, done criteria (observable outcomes).
+
+Commit:
+
+```bash
+git add -A
+git commit -m "feat(s{N}.{M}): initialize story scope
+
+In scope:
+- {item 1}
+- {item 2}
+
+Done when:
+- {criteria 1}
+- {criteria 2}
+
+Co-Authored-By: Rai <rai@humansys.ai>"
+```
+
+<verification>
+Scope commit on story branch with boundaries documented.
+</verification>
+
+### Step 3b: Update Backlog Status
+
+If the story has a backlog ticket (Jira key or local key):
+
+```bash
+rai backlog transition {story_key} in_progress
+```
+
+| Condition | Action |
+|-----------|--------|
+| Story has ticket | Transition to `in_progress` |
+| No ticket found | Skip (not all stories are tracked externally) |
+| Transition fails | Log warning and continue — backlog errors are **non-blocking** for lifecycle |
+
+<if-blocked>
+Adapter not configured or transition fails → log and continue. Backlog sync is best-effort; it must never block story work.
+</if-blocked>
+
+### Step 4: Present Next Steps
+
+Show the developer:
+- Branch name and commit hash
+- Quick scope summary
+- **Next:** `/rai-story-design` — design is not optional (PAT-186)
+
+## Output
+
+| Item | Destination |
+|------|-------------|
+| Story branch | `story/s{N}.{M}/{slug}` from `{dev_branch}` |
+| User Story | `stories/s{N}.{M}-story.md` (Connextra + Gherkin AC) |
+| Scope commit | On story branch |
+| Backlog update | via `rai backlog transition` (best-effort) |
+| Next | `/rai-story-design` |
+
+## Quality Checklist
+
+- [ ] Story branch created from `{dev_branch}` (never from an epic branch)
+- [ ] User Story created from `templates/story.md` (Connextra + Gherkin AC)
+- [ ] Scope commit documents in/out boundaries and done criteria
+- [ ] Story listed in epic scope document (if part of an epic)
+- [ ] NEVER create story branch from anything other than `{dev_branch}`
+
+## References
+
+- Next: `/rai-story-design` (always — PAT-186)
+- Complement: `/rai-story-close`
+- Epic scope: `work/epics/e{N}-{name}/scope.md`
+- Branch model: `CLAUDE.md` § Branch Model

raise_cli/skills_base/rai-story-start/templates/story.md

@@ -0,0 +1,38 @@
+---
+story_id: "{STORY_ID}"
+epic_ref: "{EPIC_ID}"
+size: "{XS|S|M|L}"
+status: "draft"
+---
+
+# Story: {title}
+
+## User Story
+As a [role],
+I want [capability],
+so that [benefit].
+
+## Acceptance Criteria
+
+### Scenario: {happy path}
+```gherkin
+Given [initial context]
+When [action]
+Then [expected outcome]
+```
+
+### Scenario: {edge case}
+```gherkin
+Given [context]
+When [action]
+Then [outcome]
+```
+
+## Examples (Specification by Example)
+
+| Input | Action | Expected Output |
+|-------|--------|-----------------|
+| [concrete value] | [concrete action] | [concrete result] |
+
+## Notes
+[Context, constraints, references to epic design.md]