raise-cli 2.2.1__py3-none-any.whl

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

@@ -0,0 +1,189 @@
+---
+name: rai-quality-review
+description: >
+  Critical code review with external auditor perspective. Catches what linters,
+  type checkers, and coverage gates miss: semantic bugs, type lies, test muda,
+  API design issues, and security concerns.
+
+license: MIT
+
+metadata:
+  raise.work_cycle: story
+  raise.frequency: on-demand
+  raise.prerequisites: story-implement
+  raise.version: "1.0.0"
+  raise.visibility: internal
+---
+
+# Quality Review
+
+## Purpose
+
+Act as an external auditor reviewing code that passed all automated gates. Find what the machines missed — semantic bugs account for 51% of all missed bugs in code review (ICSE, arxiv 2205.09428).
+
+## Mastery Levels (ShuHaRi)
+
+- **Shu**: Apply all audit categories systematically, explain each finding
+- **Ha**: Focus on highest-risk areas (type honesty, test muda), skip low-risk
+- **Ri**: Pattern-match to known vulnerability classes, minimal ceremony
+
+## Context
+
+| Condition | Action |
+|-----------|--------|
+| After `/rai-story-implement`, all gates pass | Run quality review |
+| Before `/rai-story-review` | Catch issues before retrospective |
+| Code feels "too clean" | Assumptions may be hiding — review |
+
+**Inputs:** Story ID (to find changed files), passing gates (language-appropriate linters, type checkers, test runners).
+
+## Steps
+
+### Step 0: Detect Project Language
+
+Determine the primary language and toolchain using this priority chain:
+
+1. **Check `.raise/manifest.yaml`** for explicit overrides (`project.test_command`, `project.lint_command`, `project.type_check_command`) — configuration over convention
+2. **Detect language** from `project.project_type` in manifest, or scan extensions of changed files (`git diff --name-only`)
+3. **Map language to defaults** using the table below
+
+```yaml
+# .raise/manifest.yaml — example overrides
+project:
+  test_command: "npm run test:ci"       # overrides Test Runner column
+  lint_command: "biome check"           # overrides Linter column
+  type_check_command: "tsc --noEmit"    # overrides Type Checker column
+```
+
+Manifest commands always win when present. The table is a **fallback**:
+
+| Language | Extensions | Type Checker | Linter | Test Runner |
+|----------|-----------|--------------|--------|-------------|
+| Python | `.py`, `.pyi` | pyright/mypy | ruff | pytest |
+| TypeScript | `.ts`, `.tsx` | tsc --noEmit | eslint | jest/vitest |
+| JavaScript | `.js`, `.jsx` | — | eslint | jest/vitest |
+| C# | `.cs` | dotnet build | dotnet format | xunit/nunit |
+| Java | `.java` | javac | checkstyle | JUnit |
+| Go | `.go` | go vet | golangci-lint | go test |
+| PHP | `.php` | phpstan | php-cs-fixer | phpunit |
+| Dart | `.dart` | dart analyze | dart fix | flutter test |
+
+If mixed languages, review each language group separately using its section below.
+
+### Step 1: Identify Changed Files
+
+```bash
+# Use the parent branch (epic or dev) as merge base — not a hardcoded branch name
+git diff --name-only $(git merge-base HEAD <parent-branch>)..HEAD -- '<extensions>'
+```
+
+Replace `<extensions>` with language-appropriate patterns from Step 0 (e.g., `'*.py' '*.pyi'` for Python, `'*.ts' '*.tsx'` for TypeScript).
+
+Read every changed file. You cannot review code you haven't read.
+
+### Step 2: Semantic Correctness Audit
+
+#### Universal Checks (all languages)
+
+**Logic correctness:** Inverted conditionals (#1 semantic bug), off-by-one errors, wrong variable in expressions (copy-paste), unhandled edge cases (empty, null/None, zero-length).
+
+#### Language-Specific Checks
+
+**Python:**
+- **Type honesty:** `type: ignore` comments (each is a potential lie), `cast()` honesty, annotations claiming more specific types than runtime provides
+- **Error handling:** Overly broad `except Exception`, swallowed exceptions, missing `raise X from exc`
+- **Idioms:** Mutable default arguments, late binding closures in loops
+
+**TypeScript/JavaScript:**
+- **Type honesty:** `as` type assertions (bypasses type checking), `any` types (defeats type safety), `@ts-ignore`/`@ts-expect-error` comments
+- **Error handling:** Unhandled promise rejections, missing `.catch()`, overly broad `catch(e)` without type narrowing
+- **Idioms:** `==` vs `===`, truthiness traps (`0`, `""`, `[]` are falsy), implicit `any` from untyped imports
+
+**C#/.NET:**
+- **Type honesty:** Null-forgiving operator `!` (suppresses null warnings), unchecked casts vs pattern matching, `dynamic` type usage
+- **Error handling:** Empty `catch` blocks, catching `System.Exception` broadly, missing `using`/`await using` for `IDisposable`
+- **Idioms:** `async void` methods (fire-and-forget), missing `ConfigureAwait`, LINQ deferred execution surprises
+
+**PHP:**
+- **Type honesty:** Missing type declarations, `@` error suppression operator, loose comparison (`==` vs `===`)
+- **Error handling:** Silenced errors, missing null checks on database results
+- **Idioms:** Uninitialized properties, reference parameter side effects
+
+**Go:**
+- **Type honesty:** Unchecked type assertions (use comma-ok pattern), interface satisfaction without tests
+- **Error handling:** Ignored error returns (`_`), error wrapping without `%w`
+- **Idioms:** Goroutine leaks, unbuffered channel deadlocks, deferred close on writable resources
+
+**Dart/Flutter:**
+- **Type honesty:** `as` casts without `is` checks, `dynamic` type usage, `!` null assertion operator
+- **Error handling:** Uncaught `Future` errors, missing error handling in `StreamBuilder`
+- **Idioms:** `setState` after dispose, missing `const` constructors, build method side effects
+
+### Step 3: Test Quality Audit
+
+Apply these heuristics to every test file:
+
+| # | Heuristic | Red Flag |
+|---|-----------|----------|
+| 1 | Mutation Survival | Test passes regardless of code behavior change |
+| 2 | Refactoring Resilience | Test asserts on internals, not behavior |
+| 3 | Behavior Specification | Name mirrors code structure, not behavior |
+| 4 | Magic Literal | Assertion against hardcoded value from implementation |
+| 5 | Mock Depth | Mock returns mock returns mock |
+| 6 | Deletion | No unique bug coverage if test deleted |
+| 7 | Spec Independence | Assertion requires reading source to understand |
+
+Classify: **Muda** (waste, recommend deletion) / **Fragile** (breaks on refactor) / **Valuable** (leave as-is).
+
+### Step 4: API Surface & Security Audit
+
+**API (language-adaptive):**
+
+| Language | Visibility Mechanism | Leak Detection |
+|----------|---------------------|----------------|
+| Python | Lean `__all__`, `_`-prefixed internals | Internal symbols in public API |
+| TypeScript | `export` discipline, barrel files | Re-exporting internals, `export *` |
+| C# | `internal` vs `public`, `[assembly: InternalsVisibleTo]` | Public types that should be internal |
+| Go | Capitalization (exported vs unexported) | Exported helpers that should be internal |
+| PHP | `private`/`protected` vs `public` | Public methods that should be protected |
+| Dart | `_`-prefixed private, `export` directives | Part-of files leaking implementation |
+
+**Security (universal):** Entry point trust model, input validation at boundaries, dependency justification, no secret exposure in logs/errors.
+
+### Step 5: Present Findings
+
+```markdown
+## Quality Review: {story_id}
+
+### Critical (fix before merge)
+### Recommended (improve code quality)
+### Observations (no action needed)
+### Verdict
+- [ ] PASS / PASS WITH RECOMMENDATIONS / FAIL
+```
+
+Every finding: specific file:line, WHY it matters, concrete fix suggestion.
+
+## Output
+
+| Item | Destination |
+|------|-------------|
+| Review findings | Presented inline, saved if requested |
+| Verdict | PASS, PASS WITH RECOMMENDATIONS, or FAIL |
+| Next | `/rai-story-review` |
+
+## Quality Checklist
+
+- [ ] Project language detected (Step 0) before reviewing
+- [ ] All changed files for detected language read before reviewing
+- [ ] Every finding cites specific file:line
+- [ ] Every finding explains WHY (not just WHAT)
+- [ ] Style issues already caught by language-appropriate linters are excluded
+- [ ] Language-specific checks applied from correct section
+- [ ] "No issues found" is a valid outcome — do not invent findings
+
+## References
+
+- Evidence: `work/research/quality-review/evidence-catalog.md`
+- Complements: `/rai-architecture-review` (proportionality), `/rai-story-review` (retrospective)
+- Research: ICSE semantic bugs (arxiv 2205.09428), Google Testing Blog, OWASP

raise_cli/skills_base/rai-research/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: rai-research
+description: >
+  Conduct epistemologically rigorous research to inform decisions.
+  Use before ADRs, when evaluating competing approaches, entering
+  unfamiliar domains, or resolving parking lot items. Produces
+  evidence catalogs with triangulated claims and actionable recommendations.
+
+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.0.0"
+  raise.visibility: public
+
+---
+
+# Research
+
+## Purpose
+
+Conduct epistemologically rigorous research to inform decisions. Standing on the shoulders of giants, not reinventing wheels.
+
+## Mastery Levels (ShuHaRi)
+
+- **Shu**: Follow all steps with full evidence catalog and research prompt template
+- **Ha**: Scale depth to decision importance; adapt prompt template
+- **Ri**: Create domain-specific research protocols and custom prompts
+
+## Context
+
+**When to use:** Before ADRs, when evaluating competing approaches, entering unfamiliar domains, or resolving parking lot items.
+
+**When to skip:** Decision is low-stakes and reversible, or prior research exists in `work/research/`.
+
+**Inputs:** Clear research question(s), decision context, depth constraint (quick/standard/deep).
+
+| Depth | Time | Sources | Use when |
+|-------|------|---------|----------|
+| Quick scan | 1-2h | 5-10 | Low-stakes, familiar domains |
+| Standard | 4-8h | 15-30 | Most ADRs, technology evaluation |
+| Deep dive | 2-5d | 50-100+ | Strategic decisions, unfamiliar domains |
+
+## Steps
+
+### Step 1: Frame the Question
+
+Define: primary question, secondary questions, decision this informs, depth constraint.
+
+**Epistemological principles:** Seek disconfirming evidence (falsifiability), require 3+ sources per claim (triangulation), primary > secondary > tertiary sources.
+
+<verification>
+Question is specific and falsifiable.
+</verification>
+
+<if-blocked>
+Question too vague → decompose into sub-questions.
+</if-blocked>
+
+### Step 2: Select Tool & Survey
+
+**Tool selection:**
+
+| Tool | Best for |
+|------|----------|
+| `ddgr "query"` | Quick scans, no API key needed |
+| `llm -m perplexity "query"` | Deep research with citations |
+| WebSearch | Reliable fallback |
+
+Gather sources: academic papers, official docs, GitHub repos (stars/activity), engineering blogs, community discussions.
+
+<verification>
+10+ sources collected (scaled to depth).
+</verification>
+
+### Step 3: Build Evidence Catalog
+
+Per source: type (primary/secondary/tertiary), evidence level, key finding, relevance.
+
+| Evidence level | Criteria |
+|---------------|----------|
+| Very High | Peer-reviewed, production-proven at scale, >10k stars |
+| High | Expert practitioners at established companies, >1k stars |
+| Medium | Community-validated, emerging consensus, >100 stars |
+| Low | Single source, unvalidated, <100 stars |
+
+Save to `work/research/{topic}/sources/evidence-catalog.md`.
+
+<verification>
+Evidence catalog created with levels rated.
+</verification>
+
+### Step 4: Triangulate & Synthesize
+
+Per major claim: find 3+ independent confirmations, note consensus vs disagreement, assign confidence (HIGH/MEDIUM/LOW), acknowledge contrary evidence explicitly.
+
+Extract patterns: convergence points, gaps, RaiSE-specific vs general findings.
+
+<verification>
+Major claims have 3+ sources. Contrary evidence documented.
+</verification>
+
+### Step 5: Recommend & Link
+
+Produce: recommendation with confidence level, trade-offs, implementation implications, risks.
+
+Connect to governance: create/reference ADR if architectural, update backlog if actionable, update parking lot if deferred.
+
+<verification>
+Recommendation is actionable and traces to evidence.
+</verification>
+
+## Output
+
+| Item | Destination |
+|------|-------------|
+| Report | `work/research/{topic}/{topic}-report.md` |
+| Evidence catalog | `work/research/{topic}/sources/evidence-catalog.md` |
+| Navigation | `work/research/{topic}/README.md` |
+| Next | ADR, backlog item, or parking lot update |
+
+## Quality Checklist
+
+- [ ] Research question is specific and falsifiable
+- [ ] 10+ sources consulted (scaled to depth)
+- [ ] Evidence catalog created with levels rated
+- [ ] Major claims triangulated (3+ independent sources)
+- [ ] Confidence level explicitly stated on recommendation
+- [ ] Contrary evidence acknowledged (not hidden)
+- [ ] Governance linkage established (ADR, backlog, or parking lot)
+- [ ] NEVER present single-source findings as consensus
+
+## References
+
+- Research prompt template: `references/research-prompt-template.md`
+- Existing research: `work/research/`
+- Epistemology: falsifiability, triangulation, source hierarchy

raise_cli/skills_base/rai-research/references/research-prompt-template.md

@@ -0,0 +1,317 @@
+---
+research_id: "[TOPIC]-[YYYYMMDD]"
+primary_question: "[Specific, falsifiable question]"
+decision_context: "[What this informs: ADR, feature, backlog]"
+depth: "[quick-scan|standard|deep-dive]"
+created: "[YYYY-MM-DD]"
+version: "1.0"
+template: "research-prompt-v1"
+---
+
+# Research Prompt: [Topic]
+
+> Template for structured AI research with epistemological rigor
+> Based on evidence from 20 sources (meta-research 2026-01-31)
+
+---
+
+## Role Definition
+
+You are a **Research Specialist** with expertise in **[domain]**. Your task is to conduct epistemologically rigorous research following scientific standards for evidence evaluation.
+
+**Your responsibilities:**
+- Search systematically across academic, official, and practitioner sources
+- Evaluate evidence quality using RaiSE criteria
+- Triangulate findings from 3+ independent sources per major claim
+- Document contrary evidence and uncertainty explicitly
+- Produce reproducible, auditable research outputs
+
+---
+
+## Research Question
+
+**Primary**: [Main question to answer - must be specific and falsifiable]
+
+**Secondary** (supporting questions):
+1. [Supporting question 1]
+2. [Supporting question 2]
+3. [Supporting question 3]
+
+---
+
+## Decision Context
+
+**This research will inform**: [Specific decision, ADR, story design, architecture choice, etc.]
+
+**Stakeholder**: [Who needs this information]
+
+**Timeline**: [When decision will be made]
+
+**Impact**: [Consequences of getting this wrong - why rigor matters]
+
+---
+
+## Instructions
+
+### Search Strategy
+
+Execute searches across these source types:
+
+1. **Academic sources**
+   - Google Scholar: `[specific search terms]`
+   - arXiv: `[topic keywords]`
+   - Purpose: Peer-reviewed research, theoretical foundations
+
+2. **Official documentation**
+   - [Technology/framework] official docs
+   - Standards bodies (W3C, IETF, etc.)
+   - Purpose: Authoritative technical specifications
+
+3. **Production evidence**
+   - GitHub repositories (filter: >100 stars, active maintenance)
+   - Engineering blogs: FAANG, GitLab, Atlassian, established companies
+   - Purpose: Real-world validation, battle-tested patterns
+
+4. **Community validation**
+   - Reddit (r/[relevant]), Hacker News, Discord/Slack communities
+   - Conference talks, podcasts
+   - Purpose: Emerging consensus, practitioner wisdom
+
+**Keywords to search**: [List 5-10 specific search terms]
+
+**Sources to avoid**: [If any - e.g., outdated frameworks, deprecated APIs]
+
+---
+
+### Evidence Evaluation
+
+For each source you find, assess and record:
+
+- **Type**:
+  - Primary (original research, official docs, first-hand experience)
+  - Secondary (practitioner synthesis, curated guides, tutorials)
+  - Tertiary (aggregations, summaries, listicles)
+
+- **Evidence Level** (use RaiSE engineering criteria):
+  - **Very High**: Peer-reviewed papers, official docs, OSS >10k stars with proven production use
+  - **High**: Expert practitioners at established companies, well-maintained projects >1k stars
+  - **Medium**: Community-validated resources, emerging projects >100 stars, engaged articles
+  - **Low**: Single sources, <100 stars, unvalidated claims, personal blogs without corroboration
+
+- **Key Finding**: One-line takeaway from this source
+
+- **Relevance**: How does this answer our research question?
+
+- **Date**: Publication or last update date (recency matters for tech)
+
+---
+
+### Triangulation Requirements
+
+**Minimum source counts** (scale to depth):
+- Quick scan (1-2h): 5-10 sources
+- Standard (4-8h): 15-30 sources
+- Deep dive (2-5d): 50-100+ sources
+
+**For major claims**:
+- Require **3+ independent confirmations** from different sources
+- If <3 sources: Lower confidence level or mark as "emerging/unconfirmed"
+
+**Handling disagreement**:
+- Document contrary evidence explicitly
+- Describe the nature of disagreement (methodological, contextual, temporal)
+- Don't ignore conflicts - they're valuable information
+
+**Confidence calibration**:
+- HIGH: 3+ Very High or High sources, convergent evidence, no significant contrary findings
+- MEDIUM: 2-3 sources, some convergence, minor conflicts or gaps
+- LOW: <2 sources, significant disagreement, or mostly Low evidence level
+
+---
+
+## Output Format
+
+Produce the following artifacts in `work/research/[topic]/`:
+
+### 1. Evidence Catalog (`sources/evidence-catalog.md`)
+
+For each source:
+
+```markdown
+**Source**: [Title + Link]
+- **Type**: Primary/Secondary/Tertiary
+- **Evidence Level**: Very High/High/Medium/Low
+- **Date**: [YYYY-MM-DD or YYYY]
+- **Key Finding**: [One-line takeaway]
+- **Relevance**: [How it answers the question]
+```
+
+Include summary statistics:
+- Total sources: [N]
+- Evidence distribution: Very High (X%), High (Y%), Medium (Z%), Low (W%)
+- Temporal coverage: [Date range]
+
+---
+
+### 2. Synthesis Document (`synthesis.md`)
+
+#### Major Claims (Triangulated)
+
+For each significant finding:
+
+```markdown
+**Claim [N]**: [Statement of finding]
+
+**Confidence**: HIGH/MEDIUM/LOW
+
+**Evidence**:
+1. [Source A Title](URL) - [Specific finding]
+2. [Source B Title](URL) - [Specific finding]
+3. [Source C Title](URL) - [Specific finding]
+
+**Disagreement**: [Any contrary evidence or "None found"]
+
+**Implication**: [What this means for our decision]
+```
+
+#### Patterns & Paradigm Shifts
+
+Identify recurring themes across sources:
+- What architectural patterns emerge?
+- What trade-offs are commonly discussed?
+- Any paradigm shifts in recent years?
+
+#### Gaps & Unknowns
+
+Document what you **couldn't** find:
+- Unanswered sub-questions
+- Areas with insufficient evidence
+- Topics requiring deeper investigation
+
+---
+
+### 3. Recommendation (`recommendation.md`)
+
+```markdown
+## Recommendation
+
+**Decision**: [What we should do - specific and actionable]
+
+**Confidence**: HIGH/MEDIUM/LOW
+
+**Rationale**: [Why, based on triangulated evidence - reference specific sources]
+
+**Trade-offs**: [What we're accepting/sacrificing with this choice]
+
+**Risks**: [What could go wrong]
+
+**Mitigations**: [How to address the risks]
+
+**Alternatives Considered**: [Other options and why not chosen]
+```
+
+---
+
+## Quality Criteria
+
+Your research output will be validated against this checklist:
+
+**Question & Scope**
+- [ ] Research question is specific and falsifiable
+- [ ] Decision context clearly stated
+- [ ] Scope boundaries defined (what NOT to research)
+
+**Evidence Gathering**
+- [ ] Minimum source count met (scaled to depth)
+- [ ] Mix of academic, official, and practitioner sources
+- [ ] Sources include publication/update dates
+- [ ] Evidence catalog complete with all required fields
+
+**Rigor & Validation**
+- [ ] Major claims triangulated (3+ sources)
+- [ ] Confidence levels explicitly stated for each claim
+- [ ] Contrary evidence acknowledged (if present)
+- [ ] Gaps and unknowns documented
+
+**Actionability**
+- [ ] Recommendation is specific and actionable
+- [ ] Trade-offs explicitly acknowledged
+- [ ] Risks identified with mitigations
+- [ ] Clear link to decision context
+
+**Reproducibility**
+- [ ] All sources cited with URLs
+- [ ] Search keywords documented
+- [ ] Tool/model used recorded
+- [ ] Research date recorded
+
+---
+
+## Constraints
+
+**Time**: [Specific timebox if applicable - e.g., "4 hours max"]
+
+**Focus priorities**: [What to prioritize if time-constrained]
+
+**Out of scope**: [What explicitly NOT to research]
+
+---
+
+## Reproducibility Metadata
+
+Include in final output (typically in README.md):
+
+```markdown
+**Research Metadata**:
+- Tool/model used: [e.g., "perplexity-sonar", "WebSearch", "ddgr + manual synthesis"]
+- Search date: [YYYY-MM-DD]
+- Prompt version: [From frontmatter - currently 1.0]
+- Researcher: [Agent or human name]
+- Total time: [Hours spent]
+```
+
+---
+
+## Tool Selection Guide
+
+Choose research tool based on depth and availability:
+
+| Depth | First Choice | Fallback | Always Available |
+|-------|--------------|----------|------------------|
+| Quick scan | `ddgr` | WebSearch | WebSearch |
+| Standard | `llm -m perplexity` | ddgr + synthesis | WebSearch |
+| Deep dive | `llm -m perplexity` | Manual + Task agent | WebSearch + synthesis |
+
+**Check availability**:
+```bash
+# ddgr (free, no API key)
+which ddgr
+
+# perplexity (requires llm + API key)
+llm models list | grep perplexity
+
+# WebSearch (always available)
+# Built-in capability, no check needed
+```
+
+---
+
+## Example Usage
+
+See `examples/tech-stack-evaluation-prompt.md` for a complete example of this template in use.
+
+---
+
+## References
+
+- Research kata: `.raise/katas/tools/rai-research.md`
+- Evidence catalog template: `.raise/templates/tools/evidence-catalog.md`
+- Meta-research on this template: `work/research/ai-research-prompts/`
+
+---
+
+**Template Version**: 1.0
+**Created**: 2026-01-31
+**Based on**: Meta-research with 20 sources (7 Very High, 8 High, 5 Medium evidence)
+**Last Reviewed**: 2026-01-31
+**Next Review**: 2026-04-30 (quarterly)