raise-cli 2.2.1__py3-none-any.whl

raise_cli/skills_base/rai-discover-validate/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: rai-discover-validate
+description: >
+  Validate component descriptions using confidence-tier workflow.
+  Auto-validates high-confidence, batch-reviews medium by module,
+  flags low for individual human review.
+
+license: MIT
+
+metadata:
+  raise.work_cycle: discovery
+  raise.frequency: per-project
+  raise.fase: "3"
+  raise.prerequisites: discover-scan
+  raise.next: ""
+  raise.gate: ""
+  raise.adaptable: "true"
+  raise.version: "3.0.0"
+  raise.visibility: public
+---
+
+# Discovery Validate
+
+> **Deprecated:** Use `/rai-discover` instead, which runs the full pipeline (detect → extract → describe → document → build) in one pass. This skill is kept for backward compatibility.
+
+## Purpose
+
+Validate component descriptions using a confidence-tier workflow that reduces human decisions from O(components) to O(modules + exceptions).
+
+## Mastery Levels (ShuHaRi)
+
+- **Shu**: Follow all steps, review each tier in order
+- **Ha**: Trust high-confidence auto-validation; focus on medium/low
+- **Ri**: Tune confidence thresholds for domain-specific projects
+
+## Context
+
+**When to use:** After `/rai-discover-scan` has created `work/discovery/analysis.json`.
+
+**When to skip:** All components already validated, or no `analysis.json` exists.
+
+**Inputs:** `work/discovery/analysis.json`, `work/discovery/components-draft.yaml`.
+
+## Steps
+
+### Step 1: Load & Present Overview
+
+```markdown
+## Validation Overview
+**Components:** {total}
+- High confidence (auto-validate): {N} ({%})
+- Medium confidence (module batch): {N} ({%})
+- Low confidence (individual review): {N} ({%})
+**Estimated human decisions:** ~{medium_modules + low_count}
+```
+
+<verification>
+Analysis loaded with confidence tiers.
+</verification>
+
+### Step 2: Auto-Validate High Confidence (≥70)
+
+Use `auto_purpose` and `auto_category` directly. Set `validated: true, validated_by: auto`.
+
+Ask user: "Auto-validate {N} high-confidence components? [Approve all / Review individually]"
+
+<verification>
+High-confidence components marked validated.
+</verification>
+
+### Step 3: Batch Review Medium Confidence (40-69)
+
+For each module group from `analysis.json`:
+
+| # | Name | Kind | Category | Purpose | Score |
+|---|------|------|----------|---------|-------|
+| 1 | {name} | {kind} | {auto_category} | {purpose} | {score} |
+
+Ask per module: "Approve batch? [Approve all / Edit specific / Skip module]"
+
+For C#/large projects with single-file modules: group by namespace prefix instead.
+
+<verification>
+Module batches processed.
+</verification>
+
+### Step 4: Handle Low Confidence (<40)
+
+**Scale gate:** If all components are low AND count >50, offer alternative modes:
+
+| Mode | Best for | Strategy |
+|------|----------|----------|
+| A: By layer | Clean Architecture / CQRS | Group by top-level namespace, approve per layer |
+| B: Key components | Large infra-heavy codebases | User nominates 10-20 key components, bulk-skip rest |
+| C: Naming pattern | Consistent suffix patterns | Auto-accept by pattern (`*Handler`, `*Repository`) |
+
+Otherwise, review individually — present file, signature, signals, ask: Approve / Edit / Skip.
+
+<verification>
+Low-confidence components reviewed or alternative mode applied.
+</verification>
+
+### Step 5: Export & Save
+
+1. Update `components-draft.yaml` with validation states
+2. Export validated components to `work/discovery/components-validated.json` (graph node format)
+3. Update `work/discovery/context.yaml` status to `complete`
+
+**Graph node format:**
+```json
+{"id": "comp-scanner-symbol", "type": "component", "content": "purpose",
+ "source_file": "path", "metadata": {"name": "...", "kind": "...", "validated_by": "..."}}
+```
+
+Present summary: total, auto-validated, batch-reviewed, individual, skipped, decision reduction %.
+
+<verification>
+`components-validated.json` created. Context status updated.
+</verification>
+
+## Output
+
+| Item | Destination |
+|------|-------------|
+| Updated draft | `work/discovery/components-draft.yaml` |
+| Validated catalog | `work/discovery/components-validated.json` |
+| Next | `rai graph build` or `/rai-discover-document` |
+
+## Quality Checklist
+
+- [ ] High-confidence auto-validation approved by user before proceeding
+- [ ] Medium batches presented with full context (module, category, purpose)
+- [ ] Scale gate checked before attempting O(components) individual review
+- [ ] Export uses graph node format (id, type, content, source_file, metadata)
+- [ ] NEVER skip the scale gate for all-low scenarios (>50 components)
+
+## References
+
+- Previous: `/rai-discover-scan`
+- Next: `rai graph build` or `/rai-discover-document`
+- CLI: `rai discover analyze --help`
+- Confidence tiers: high ≥70, medium 40-69, low <40

raise_cli/skills_base/rai-docs-update/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: rai-docs-update
+description: >
+  Compare knowledge graph against module architecture docs and update
+  drifted fields. Deterministic frontmatter comparison using existing
+  rai graph commands, with inference for narrative sections. HITL
+  before any writes.
+
+license: MIT
+
+metadata:
+  raise.work_cycle: utility
+  raise.frequency: per-story
+  raise.fase: ""
+  raise.prerequisites: ""
+  raise.next: ""
+  raise.gate: ""
+  raise.adaptable: "true"
+  raise.version: "2.0.0"
+  raise.visibility: public
+---
+
+# Docs Update
+
+## Purpose
+
+Close the coherence loop between code and architecture docs. Compare knowledge graph truth against module doc frontmatter, update drifted fields, and optionally refresh narrative sections.
+
+## Mastery Levels (ShuHaRi)
+
+- **Shu**: Present every diff, ask before every change
+- **Ha**: Batch frontmatter changes with single HITL gate, narrative only for structural changes
+- **Ri**: Autonomous frontmatter updates, HITL only for narrative
+
+## Context
+
+**When to use:** After stories that changed code structure, during `/rai-story-close`, after discovery refresh.
+
+**When to skip:** Stories that only changed tests/docs/non-code. No graph available.
+
+**Inputs:** Knowledge graph (`.raise/rai/memory/index.json`), module docs (`governance/architecture/modules/*.md`).
+
+## Steps
+
+### Step 1: Build Graph & Identify Affected Modules
+
+```bash
+rai graph build
+```
+
+Read `.raise/rai/personal/last-diff.json` for changed modules. If no diff or no affected_modules, check all modules.
+
+<verification>
+Module list identified for comparison.
+</verification>
+
+### Step 2: Compare Frontmatter Per Module
+
+```bash
+rai graph context mod-{name} --format json
+```
+
+Compare doc-declared vs code-truth:
+
+| Doc field | Graph truth | Comparison |
+|-----------|------------|------------|
+| `depends_on` | `code_imports` | Sort both, compare sets |
+| `depended_by` | Reverse lookup from other modules | Computed |
+| `public_api` | `code_exports` | Sort both, compare sets |
+| `components` | `code_components` | Direct number |
+
+**Fields the skill MUST NOT touch:** `purpose`, `constraints`, `status`, `entry_points`, `name`, `type`.
+
+<verification>
+Drifted fields identified per module.
+</verification>
+
+### Step 3: HITL Gate — Apply Frontmatter
+
+Present drift report:
+```
+### mod-memory
+  depends_on: [config] → [config, schemas]  (added: schemas)
+  components: 30 → 34
+```
+
+Ask: "Apply frontmatter updates to N modules? [y/n/selective]"
+
+Apply changes to YAML frontmatter only — preserve all other content and field ordering.
+
+<verification>
+Frontmatter updates applied (or skipped by user).
+</verification>
+
+### Step 4: Narrative Review (if triggered)
+
+**Trigger A (full review):** New/removed modules, major dependency changes (>2), significant API changes (>5).
+
+**Trigger B (targeted scan):** For any frontmatter change, scan prose for stale hardcoded values (old counts, removed dependency names, removed API names). These are mechanical text fixes.
+
+Present proposed changes as diff. HITL approval before writing.
+
+<verification>
+Narrative changes applied or no triggers found.
+</verification>
+
+### Step 5: Rebuild & Summarize
+
+If any changes applied:
+```bash
+rai graph build
+```
+
+Present summary: modules checked, frontmatter updated, narrative updated, graph rebuilt.
+
+<verification>
+Graph reflects updated docs. Coherence loop closed.
+</verification>
+
+## Output
+
+| Item | Destination |
+|------|-------------|
+| Updated frontmatter | `governance/architecture/modules/*.md` |
+| Narrative changes | `governance/architecture/modules/*.md` (with HITL) |
+| Summary | Displayed |
+
+## Quality Checklist
+
+- [ ] Graph built fresh before comparison (not stale data)
+- [ ] Only machine-owned fields updated (depends_on, depended_by, public_api, components)
+- [ ] Human-owned fields preserved (purpose, constraints, status, entry_points)
+- [ ] HITL gate before any writes — present diff first
+- [ ] Graph rebuilt after changes to close coherence loop
+- [ ] NEVER modify purpose or constraints without explicit human request
+
+## References
+
+- ADR-025: Incremental Coherence — Graph Diffing and AI-Driven Doc Regeneration
+- Module docs: `governance/architecture/modules/*.md`
+- Graph: `.raise/rai/memory/index.json`
+- Graph context: `rai graph context mod-{name} --format json`

raise_cli/skills_base/rai-doctor/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: rai-doctor
+description: >
+  Run RaiSE self-diagnostics, explain results conversationally, and guide
+  the user through fixes. The CLI does the checking; the skill does the
+  interpreting and helping.
+
+license: MIT
+
+metadata:
+  raise.work_cycle: utility
+  raise.frequency: as-needed
+  raise.fase: "0"
+  raise.prerequisites: ""
+  raise.next: ""
+  raise.gate: ""
+  raise.adaptable: "true"
+  raise.version: "2.2.0"
+  raise.visibility: public
+---
+
+# Doctor
+
+## Purpose
+
+Diagnose RaiSE setup health, explain issues in plain language, and guide the user through resolution. The user never touches the CLI directly — Rai runs the diagnostics and translates results into actionable conversation.
+
+## Context
+
+**When to use:** User reports something isn't working, after `rai init`, after upgrading raise-cli, or proactively at session start when setup feels off.
+
+**When to skip:** The issue is clearly in user code, not RaiSE configuration.
+
+## Steps
+
+### Step 1: Run diagnostics
+
+```bash
+rai doctor --json
+```
+
+Parse the JSON output. Categorize results by severity.
+
+### Step 2: Report to user
+
+**If all checks pass:**
+> Your RaiSE setup is healthy. All checks passed.
+
+**If there are warnings or errors**, explain each one conversationally:
+
+- Translate technical check IDs into human language
+- Group by category (environment, project, adapters, skills, MCP)
+- For each issue: what it means, why it matters, and what to do
+
+Example:
+> I found 2 issues with your setup:
+>
+> 1. **Graph is outdated** — your knowledge graph hasn't been rebuilt since governance files changed. This means my context queries may return stale data. I can rebuild it now if you'd like.
+>
+> 2. **MCP server 'jira' is unreachable** — the Jira integration can't connect. Check that JIRA_URL and JIRA_API_TOKEN are set in your environment.
+
+### Step 3: Offer fixes
+
+For auto-fixable issues (those with `fix_id` in the JSON):
+
+> I can fix issue #1 automatically. Should I run `rai doctor --fix`?
+
+Wait for user confirmation before running fixes.
+
+```bash
+rai doctor --fix
+```
+
+Report the outcome of each fix.
+
+### Step 4: Guide manual fixes
+
+For issues that can't be auto-fixed, guide step by step:
+
+- Missing env vars → tell the user exactly which vars to set and where
+- Missing optional extras → provide the exact pip install command
+- Stale skills → offer to run `rai skill sync`
+- Invalid manifest → explain what's wrong and how to fix it
+
+### Step 5: Bug report (if unresolvable)
+
+If issues persist after fixes:
+
+> This looks like a bug in RaiSE itself. I can generate a diagnostic report for the team. It only includes non-sensitive data (versions, check results, file names — never secrets or code). Want me to prepare it?
+
+If the user agrees:
+
+```bash
+rai doctor report
+```
+
+Show the user the saved report path so they can review it. Then:
+
+> The report is saved at {path}. Review it, and when ready I can open your email client to send it:
+
+```bash
+rai doctor report --send
+```
+
+## Output
+
+| Artifact | When |
+|----------|------|
+| Diagnostic summary | Always (conversational) |
+| Auto-fixes applied | When user approves --fix |
+| Report file | When user requests bug report |
+| Email draft | When user approves --send |
+
+## Quality Checklist
+
+- [ ] Never run `--fix` without user confirmation
+- [ ] Explain issues in plain language, not technical jargon
+- [ ] Never expose secrets, tokens, or file contents in conversation
+- [ ] Offer bug report only after fix attempts fail
+- [ ] Always show the report path so user can review before sending

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

@@ -0,0 +1,165 @@
+---
+name: rai-epic-close
+description: >
+  Complete an epic with retrospective, metrics capture, and tracking update.
+  No branch merge — epics are logical containers. Story branches merge
+  directly to the development branch during story-close.
+
+license: MIT
+
+metadata:
+  raise.work_cycle: epic
+  raise.frequency: per-epic
+  raise.fase: "9"
+  raise.prerequisites: all stories complete
+  raise.next: ""
+  raise.gate: ""
+  raise.adaptable: "true"
+  raise.version: "3.0.0"
+  raise.visibility: public
+  raise.inputs: |
+    - scope: file_path, required, previous_skill
+    - all_retrospectives: boolean, required, git
+    - dev_branch: string, required, config
+  raise.outputs: |
+    - retrospective: file_path, file
+    - tag: string, git
+---
+
+# Epic Close
+
+## Purpose
+
+Complete an epic by conducting a retrospective, tagging the milestone, and updating tracking. No branch merge needed — stories already merged to the development branch during story-close.
+
+## Mastery Levels (ShuHaRi)
+
+- **Shu**: Follow all steps, complete full retrospective template
+- **Ha**: Adjust retrospective depth based on epic complexity
+- **Ri**: Integrate with release workflows, automate metrics extraction
+
+## Context
+
+**When to use:** All stories complete and merged to `{dev_branch}`. Ready to close the epic lifecycle.
+
+**When to skip:** Epic abandoned (document why, update backlog as "Abandoned").
+
+**Inputs:** Epic scope document, all story retrospectives, passing test suite.
+
+**Branch config:** Read `branches.development` from `.raise/manifest.yaml` for `{dev_branch}`. Default: `main`.
+
+## Steps
+
+### Step 1: Verify Stories Complete
+
+Check all stories are done in the epic scope document:
+
+```bash
+grep -E "^\s*-\s*\[ \]" "work/epics/e{N}-{name}/scope.md"
+```
+
+| Condition | Action |
+|-----------|--------|
+| All stories checked | Continue |
+| Incomplete stories | Complete them first or explicitly descope |
+
+<verification>
+All stories marked complete in epic scope.
+</verification>
+
+### Step 2: Run Tests & Write Retrospective
+
+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
+
+| 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.
+
+Create retrospective at `work/epics/e{N}-{name}/retrospective.md` using `templates/retrospective.md`. Fill from story retrospectives and git history.
+
+<verification>
+Tests green. Retrospective created with metrics, patterns, and process insights.
+</verification>
+
+<if-blocked>
+Tests failing → fix before closing.
+</if-blocked>
+
+### Step 3: Tag Epic Milestone
+
+Tag the current `{dev_branch}` HEAD to mark epic completion:
+
+```bash
+git tag -a "epic/e{N}-complete" -m "Epic E{N}: {Epic Name} complete
+
+Delivered: [key deliverables]
+Stories: N stories
+
+Co-Authored-By: Rai <rai@humansys.ai>"
+```
+
+Commit retrospective and any final artifacts:
+
+```bash
+git add -A
+git commit -m "epic(e{N}): close with retrospective
+
+Co-Authored-By: Rai <rai@humansys.ai>"
+```
+
+<verification>
+Tag created. Retrospective committed.
+</verification>
+
+### Step 4: Update Backlog & Context
+
+1. Mark epic complete in `governance/backlog.md` (status → `✅ Complete`)
+2. Update `CLAUDE.local.md` to reflect completion and next epic
+3. Emit telemetry:
+
+```bash
+rai signal emit-work epic E{N} --event complete
+```
+
+<verification>
+Backlog reflects completion. Local context updated.
+</verification>
+
+## Output
+
+| Item | Destination |
+|------|-------------|
+| Retrospective | `work/epics/e{N}-{name}/retrospective.md` |
+| Tag | `epic/e{N}-complete` on `{dev_branch}` |
+| Backlog update | `governance/backlog.md` |
+| Context update | `CLAUDE.local.md` |
+
+## Quality Checklist
+
+- [ ] All stories complete before closing (gate)
+- [ ] Tests pass before closing
+- [ ] Retrospective captures metrics, patterns, and process insights
+- [ ] Epic milestone tagged on `{dev_branch}`
+- [ ] Backlog updated with completion status
+- [ ] No epic branch to clean up — epics are logical containers
+- [ ] NEVER close without retrospective — learnings compound across epics
+
+## References
+
+- Retrospective template: `templates/retrospective.md`
+- Previous: All `/rai-story-close` completions
+- Backlog: `governance/backlog.md`
+- Next: `/rai-epic-design` for next epic

raise_cli/skills_base/rai-epic-close/templates/retrospective.md

@@ -0,0 +1,68 @@
+# Epic Retrospective: E{N} {Epic Name}
+
+**Completed:** YYYY-MM-DD
+**Duration:** X days (started YYYY-MM-DD)
+**Stories:** N stories delivered
+
+---
+
+## Summary
+
+[2-3 sentence summary of what was delivered and its impact]
+
+## Metrics
+
+| Metric | Value | Notes |
+|--------|-------|-------|
+| Stories Delivered | N | |
+| Story Points | X SP | |
+| Tests Added | N | |
+| Average Velocity | X.Xx | vs baseline |
+| Calendar Days | N | |
+
+### Story Breakdown
+
+| Story | Size | SP | Velocity | Key Learning |
+|-------|:----:|:--:|:--------:|--------------|
+| S{N}.1 | S | 2 | 2.5x | [learning] |
+| S{N}.2 | M | 3 | 3.0x | [learning] |
+
+## What Went Well
+
+- [Positive outcome 1]
+- [Positive outcome 2]
+
+## What Could Be Improved
+
+- [Improvement area 1]
+- [Improvement area 2]
+
+## Patterns Discovered
+
+| ID | Pattern | Context |
+|----|---------|---------|
+| PAT-XXX | [pattern description] | [when to apply] |
+
+## Process Insights
+
+- [Insight about RaiSE methodology]
+- [Insight about collaboration]
+
+## Artifacts
+
+- **Scope:** `work/epics/e{N}-{name}/scope.md`
+- **Stories:** `work/epics/e{N}-{name}/stories/`
+- **ADRs:** [list any ADRs created]
+- **Tests:** N new tests
+
+## Release Impact
+
+**Release:** REL-{id} ({release name})
+**Epic progress:** {N}/{total} epics complete for this release
+
+> Include this section only when the epic belongs to a release.
+
+## Next Steps
+
+- [What follows this epic]
+- [Dependencies unblocked]