incitaciones 0.1.0

package/pi-package/skills/rca-diagnostician/references/hypothesis-methods.md

@@ -0,0 +1,53 @@
+## Hypothesis Generation and Method Selection
+
+### Multi-Level Hypothesis Generation
+
+Produce at least three candidate root causes across different analytical levels:
+
+- **Mechanism level**: What physical, logical, or behavioral process failed? (e.g., memory leak, O-ring degradation, medication dosage calculation error)
+- **Process control level**: What check, barrier, or monitoring should have caught it? (e.g., missing alert threshold, no pre-deployment validation, absent second-check protocol)
+- **Organizational level**: What policy, incentive, resource, or cultural factor enabled the failure? (e.g., staffing pressure, incentive misalignment, deferred maintenance, blame culture suppressing reports)
+
+### Method Selection Guide
+
+Select based on domain, evidence, and the question being asked:
+
+| Method | Best when | Domain fit |
+|--------|-----------|------------|
+| **5 Whys** | Fast initial exploration; small team | Any — but stop only when you reach a system-modifiable cause |
+| **Fishbone/Ishikawa** | Brainstorming across cause categories | Any — team-friendly for cross-functional groups |
+| **FTA (Fault Tree)** | Combinations of failures matter; system architecture available | Engineering, manufacturing, safety |
+| **FMEA/FMECA** | Preventive analysis of components/processes; need risk ranking | Engineering, manufacturing, design |
+| **STAMP/STPA** | Complex sociotechnical systems with control interactions | Aviation, healthcare, autonomous systems |
+| **Causal inference (DAG/SCM)** | Need to identify intervention effects formally; confounding is a concern | Social science, policy, epidemiology |
+| **Qualitative inquiry** | Practices, incentives, or culture are the suspected drivers | Organizational, healthcare, education |
+| **Bayesian networks** | Multiple uncertain evidence streams; need probabilistic diagnosis | Engineering, medical diagnostics, security |
+| **Postmortem (structured)** | Software/infrastructure incidents; need detection-response-recovery analysis | Software, IT operations, security |
+
+### Hypothesis Testing
+
+For each candidate cause, answer:
+
+1. **What evidence supports it?** (cite specific sources from evidence inventory)
+2. **What evidence contradicts it?** (actively seek disconfirming data)
+3. **What would falsify it?** (define the test that would eliminate this hypothesis)
+4. **Is the mechanism plausible?** (can you explain how X causes Y, not just that X correlates with Y?)
+5. **Causal role**: Is it necessary? Sufficient? Or a contributing factor?
+
+### Differentiating Causal Levels
+
+- **Contributing factor**: Exacerbated the outcome or increased its likelihood, but did not directly initiate it
+- **Root cause**: The specific mechanism or broken process that, if removed, would have prevented the outcome
+- **Latent/generic cause**: The overarching systemic flaw that allowed the root cause to exist (e.g., flawed policy, missing training program, cultural norm). Fixing these yields the highest ROI.
+
+### Output
+
+```text
+## Hypotheses
+
+| # | Level | Candidate cause | Supporting evidence | Contradicting evidence | Falsification test | Status |
+|---|-------|-----------------|--------------------|-----------------------|-------------------|--------|
+| 1 | [mechanism/process/org] | [hypothesis] | [evidence] | [evidence] | [what would disprove] | [supported/weakened/falsified] |
+
+Method selected: [method] — Rationale: [why this method fits the domain and evidence]
+```

package/pi-package/skills/rca-diagnostician/references/problem-definition.md

@@ -0,0 +1,34 @@
+## Problem Definition
+
+Define the outcome precisely before investigating causes.
+
+### Required Elements
+
+1. **WHAT** — Specific observable outcome (not interpretation)
+2. **WHERE** — System, component, location, scope
+3. **WHEN** — First detection, duration, resolution
+4. **SEVERITY** — Impact on users, safety, business, compliance
+5. **OUT OF SCOPE** — What this investigation does not cover
+
+### Counterfactual
+
+State the expected/normal behavior and what changed relative to that baseline. This anchors the investigation — without a counterfactual, you cannot distinguish cause from background condition.
+
+### Red Flags
+
+- Problem statement contains solutions ("we need to add...")
+- Describes a symptom without measurable specificity ("the system is slow")
+- No severity assessment — all problems feel urgent without scoping
+- Scope is unbounded — investigation will grow without limit
+
+### Output
+
+```text
+## Problem Definition
+
+Outcome: [precise statement]
+Measurement: [how detected/measured]
+Severity: [impact assessment]
+Counterfactual: [expected vs. actual]
+Scope boundary: [in scope / out of scope]
+```

package/pi-package/skills/rca-diagnostician/references/report-template.md

@@ -0,0 +1,75 @@
+```text
+# RCA Diagnostician Report
+
+Date: [YYYY-MM-DD]
+Mode: [INVESTIGATE | EVALUATE]
+Domain: [discipline/context]
+
+## Problem Definition
+
+Outcome: [precise statement of what failed]
+Measurement: [how detected/measured]
+Severity: [impact assessment]
+Counterfactual: [expected vs. actual behavior]
+Scope boundary: [in scope / out of scope]
+
+## Evidence Summary
+
+Sources: [count] across [count] independent streams
+Sufficiency: [MET | GAP — describe]
+
+## Timeline (key events)
+
+| Time | Event | Source |
+|------|-------|--------|
+| [when] | [what happened] | [evidence source] |
+
+## Root Causes Identified
+
+| # | Level | Root cause | Confidence | Key evidence |
+|---|-------|-----------|------------|--------------|
+| 1 | [mechanism/process/org] | [cause] | [high/medium/low] | [supporting evidence] |
+
+## Bias Check Summary
+
+- Confirmation bias: [CLEAR | FLAG]
+- Blame displacement: [CLEAR | FLAG]
+- Correlation-causation: [CLEAR | FLAG]
+- Early closure: [CLEAR | FLAG]
+
+Countermeasure actions taken: [what was done to mitigate flagged biases]
+
+## Corrective Actions
+
+| # | Root cause | Action | Strength | Owner | Deadline | Verification metric | Monitoring period |
+|---|-----------|--------|----------|-------|----------|--------------------|--------------------|
+| 1 | [cause] | [action] | [strong/intermediate/weak] | [who] | [when] | [metric] | [duration] |
+
+Action strength mix: [N strong, N intermediate, N weak]
+Minimum strong action: [MET | NOT MET]
+
+## Rigor Assessment
+
+Overall: [STRONG | ADEQUATE | WEAK | INSUFFICIENT]
+Key gaps: [list any PARTIAL or NOT MET criteria]
+
+## Recommendations
+
+1. [Most critical action — with owner and deadline]
+2. [Next priority]
+3. [Follow-up or monitoring action]
+
+## Open Questions
+
+- [What remains uncertain]
+- [What evidence is still needed]
+- [What assumptions should be monitored]
+
+## Learning Loop
+
+- Standards to update: [list]
+- Training to modify: [list]
+- Design reviews to inform: [list]
+- Monitoring to add/change: [list]
+- Audit/compliance to introduce: [list]
+```

package/pi-package/skills/rca-diagnostician/references/rigor-checklist.md

@@ -0,0 +1,66 @@
+## Rigor Evaluation Checklist
+
+Apply to your own RCA (self-check) or to an existing report (EVALUATE mode).
+
+### Core Criteria (always apply)
+
+| # | Criterion | What to check | MET when |
+|---|-----------|---------------|----------|
+| 1 | **Problem definition** | Is the outcome measurable, time-bounded, and severity-scoped? | WHAT/WHERE/WHEN/SEVERITY all specified; no solution language embedded |
+| 2 | **Counterfactual** | Is the expected/normal behavior stated? | Explicit baseline; change from normal identified |
+| 3 | **Evidence sufficiency** | Are there at least three independent evidence streams? | 3+ distinct source types (records, observation, testimony, artifacts) |
+| 4 | **Hypothesis discipline** | Were alternative hypotheses documented with falsification criteria? | 3+ candidates at different levels; disconfirming evidence sought for each |
+| 5 | **Mechanism plausibility** | Is each claimed cause explained by mechanism, not just correlation? | "How X causes Y" stated; not just "X preceded Y" |
+| 6 | **Action quality** | Do actions materially change system constraints? | At least 1 strong action; weak-only portfolios flagged |
+| 7 | **Ownership** | Is there a named owner, deadline, and authority for each action? | Every action row complete |
+| 8 | **Effectiveness verification** | Are verification metrics and monitoring periods defined? | Metric + period + escalation path for each action |
+| 9 | **Learning loop** | Does the RCA feed back into standards, training, and monitoring? | At least one organizational update identified |
+
+### AI Governance Criteria (apply when AI tools were used in the investigation)
+
+| # | Criterion | What to check | MET when |
+|---|-----------|---------------|----------|
+| 10 | **Provenance** | Does every AI-produced claim link to evidence artifacts? | Each AI output traceable to source data |
+| 11 | **Explainability** | Are AI outputs interpretable and connected to interventions? | Explanations are meaningful to domain practitioners |
+| 12 | **Causal guardrails** | Were associations distinguished from causal claims? | Uncertainty stated; no bare "AI found the root cause" |
+| 13 | **Human decision rights** | Did accountable humans review and approve findings? | Named reviewer signed off on AI-informed conclusions |
+
+### Scoring
+
+- **MET**: Criterion fully satisfied with evidence
+- **PARTIAL**: Criterion addressed but with gaps or weak evidence
+- **NOT MET**: Criterion absent or inadequate
+
+Overall rigor (based on 9 core criteria):
+- **STRONG**: All 9 core criteria MET
+- **ADEQUATE**: No more than 2 PARTIAL, zero NOT MET
+- **WEAK**: 1-2 NOT MET or 3+ PARTIAL
+- **INSUFFICIENT**: 3+ NOT MET
+
+AI governance criteria do not affect the core rigor score but are reported separately. If any AI governance criterion is NOT MET, append "(AI governance gaps)" to the overall rigor rating.
+
+### Output
+
+```text
+## Rigor Evaluation
+
+| # | Criterion | Status | Evidence/Gap |
+|---|-----------|--------|-------------|
+| 1 | Problem definition | [MET/PARTIAL/NOT MET] | [detail] |
+| 2 | Counterfactual | [MET/PARTIAL/NOT MET] | [detail] |
+| 3 | Evidence sufficiency | [MET/PARTIAL/NOT MET] | [detail] |
+| 4 | Hypothesis discipline | [MET/PARTIAL/NOT MET] | [detail] |
+| 5 | Mechanism plausibility | [MET/PARTIAL/NOT MET] | [detail] |
+| 6 | Action quality | [MET/PARTIAL/NOT MET] | [detail] |
+| 7 | Ownership | [MET/PARTIAL/NOT MET] | [detail] |
+| 8 | Effectiveness verification | [MET/PARTIAL/NOT MET] | [detail] |
+| 9 | Learning loop | [MET/PARTIAL/NOT MET] | [detail] |
+
+AI governance (if applicable):
+| 10 | Provenance | [MET/PARTIAL/NOT MET/N/A] | [detail] |
+| 11 | Explainability | [MET/PARTIAL/NOT MET/N/A] | [detail] |
+| 12 | Causal guardrails | [MET/PARTIAL/NOT MET/N/A] | [detail] |
+| 13 | Human decision rights | [MET/PARTIAL/NOT MET/N/A] | [detail] |
+
+Overall rigor: [STRONG | ADEQUATE | WEAK | INSUFFICIENT]
+```

package/pi-package/skills/red-team-review/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: red-team-review
+description: "Red-team-style adversarial review finding logic bugs, failure modes, security vulnerabilities, and deployment risks"
+metadata:
+  installed-from: "incitaciones"
+---
+<!-- Full version: content/prompt-task-red-team-review.md -->
+Act as a Senior Software Engineer running a red team diagnostic. Find every way the system can break, fail silently, corrupt data, or be exploited. Review the provided [INPUT] across four domains. Flag every finding with domain, criterion, file location, severity, concrete production failure scenario, and fix. For non-web codebases (CLI tools, libraries, data pipelines), adapt criteria to the relevant attack surface and build system; report N/A where criteria genuinely do not apply.
+
+## Domain 1: Logic & Correctness
+
+Targets edge cases in internal logic; for external input validation see 2.4.
+
+### 1.1 Boundary Conditions & Edge Cases
+- Flag numeric ops not handling: zero, negative, overflow/underflow, NaN, Infinity.
+- Flag collection ops not handling: empty, single-element, at-capacity.
+- Flag string ops not handling: empty, whitespace-only, Unicode edge cases (ZWJ, RTL, emoji), exceeding length.
+- Flag date/time ops not handling: timezone conversion, DST, leap years/seconds, epoch boundaries.
+
+### 1.2 State & Data Integrity
+- Flag state machines with unvalidated transitions or unreachable/inescapable states.
+- Flag read-modify-write on shared data without lock/transaction/atomic (race conditions).
+- Flag partial mutation before possible failure without rollback (inconsistent state).
+- Flag caches servable stale after source-of-truth change without invalidation/TTL.
+
+### 1.3 Comparison & Equality
+- Flag float equality (`==`/`===`) — require epsilon comparison.
+- Flag sort/compare not handling nulls, undefined, mixed types.
+- Flag case-sensitive comparison on user identifiers where case-insensitive is intent.
+- Flag locale-dependent string ops on multi-locale data.
+
+### 1.4 Resource & Lifecycle
+- Flag resources (files, connections, sockets) not guaranteed to close in all paths (including exceptions).
+- Flag event listeners/timers registered but never unregistered (memory leaks).
+- Flag retry logic without max attempts or backoff (cascade failures).
+- Flag main thread/event loop blocking (>50ms UI, >100ms server).
+
+## Domain 2: Failure Modes & Reliability
+
+### 2.1 Error Propagation
+- Flag silent error swallowing (empty catch, log-only without re-throw/error return).
+- Flag broad exception catches masking unrelated bugs.
+- Flag unhandled async rejections (promises, futures).
+- Flag functions returning "success" on failure paths — callers proceed with bad data.
+
+### 2.2 Dependency Failures
+- Flag external calls (HTTP, DB, API, filesystem) with **no timeout** — causes indefinite hangs.
+- Flag external service integrations with **no resilience mechanism** (retry with backoff, circuit breaker, fallback, or timeout) at either the call site or client/middleware level — single dependency cascades to total failure.
+- Flag assumptions of always-available network or always-successful disk writes.
+
+### 2.3 Concurrency & Ordering
+- Flag operations depending on concurrent task execution order without synchronization.
+- Flag event/queue processing without idempotency (at-least-once requires dedup).
+- Flag check-then-act without atomicity — Time-of-Check-to-Time-of-Use (TOCTOU).
+- Flag shared counters/balances outside atomic operations.
+
+### 2.4 Data Validation at Boundaries
+
+Targets trust boundaries where external data enters the system; for internal logic edge cases see 1.1.
+
+- Flag external input used without type checking and range validation.
+- Flag deserialization of external data without malformed-input handling.
+- Flag inter-service communication trusting schema without validation.
+- Flag DB query results assumed non-null/non-empty without checks.
+
+## Domain 3: Security & Attack Surface
+
+### 3.1 Injection Flaws
+- Flag SQL via string concatenation — require parameterized queries.
+- Flag OS command execution with user input — require argument arrays/allowlisting.
+- Flag unescaped user input in HTML — verify auto-escaping, flag bypasses (`dangerouslySetInnerHTML`, `| safe`, `{!! !!}`, `v-html`).
+- Flag `eval`/`Function()` on user-derived data.
+
+### 3.2 Authentication & Authorization
+- Flag user enumeration via differing auth error messages ("user not found" vs "wrong password").
+- Flag session tokens or JWTs in `localStorage` (XSS-accessible). Verify `httpOnly`/`secure`/`SameSite` cookies.
+- Flag endpoints performing sensitive operations without server-side authorization — client-side-only auth is no auth.
+- Flag insecure direct object references (IDOR): ID parameter changes granting cross-user access without ownership check.
+
+### 3.3 Data Exposure
+- Flag stack traces, schema, paths, versions in client errors.
+- Flag sensitive data in logs (passwords, tokens, PII).
+- Flag over-fetching exposing admin fields, internal IDs, or other users' data.
+- Verify HTTPS. Flag CORS wildcard on auth endpoints.
+
+### 3.4 AI/LLM Integration *(skip if no AI components)*
+- Flag user input in system prompts without structural separation (prompt injection).
+- Flag unsanitized RAG content in prompts (indirect injection).
+- Flag destructive LLM-callable tools without user confirmation.
+- Flag LLM output used in HTML/queries/commands without sanitization — treat as untrusted.
+- Flag agentic systems without iteration limits, cost caps, human-in-the-loop.
+
+## Domain 4: CI/CD & Deployment Safety
+
+### 4.1 Pipeline Injection & Supply Chain
+- Flag actions pinned by **mutable tag** — require **commit SHA**. Flag `${{ }}` interpolation of user-controlled input in `run:` — require `env:`. Flag `pull_request_target` + PR head checkout. Flag `curl | bash` and installs without lockfiles.
+
+### 4.2 Secret & Permission Hygiene
+- Flag secrets in outputs/logs. Flag secrets accessible during untrusted input processing. Verify least-privilege `permissions:`. Flag self-hosted runners on public repos.
+
+### 4.3 Deployment Safety
+- Flag deploys with no rollback. Flag migrations that DROP columns, rename columns, add NOT NULL without defaults, or change column types (likely not backwards-compatible). Flag deploys without health checks. Flag undocumented staging/prod config differences.
+
+### 4.4 Test & Gating Gaps
+- Check for SAST/DAST/SCA/secret scanning as **blocking gates**. Flag gates only on default branch. Flag test suites passable with zero tests. Flag deploys proceeding on skipped/cancelled tests.
+
+## Output Format
+
+Per domain:
+```
+## Domain N: [Name]
+Status: PASS | FAIL | PARTIAL
+### Findings
+[RED-N.M] [CRITICAL|HIGH|MEDIUM|LOW] — [file:line]
+  Finding: [Bug, failure mode, or vulnerability]
+  Scenario: [How this manifests in production]
+  Fix: [Actionable remediation]
+### Passes
+- [What was correct]
+```
+
+Severity: CRITICAL = data corruption/loss/breach/total failure. HIGH = significant incorrect behavior under common conditions. MEDIUM = edge-case bugs or missing resilience. LOW = minor gaps, low probability.
+
+Conclude with:
+```
+## Summary
+- Domain 1 (Logic): [PASS|FAIL|PARTIAL]
+- Domain 2 (Reliability): [PASS|FAIL|PARTIAL]
+- Domain 3 (Security): [PASS|FAIL|PARTIAL]
+- Domain 4 (CI/CD): [PASS|FAIL|PARTIAL]
+Overall: [SOLID | NEEDS_HARDENING | FRAGILE]
+Top 3 Critical Findings: [list]
+Highest-Risk Area: [domain and why]
+```
+
+If no findings in a domain, mark PASS with a brief note on what was correct. Do not fabricate findings.
+
+[INPUT]:
+{provide_code_config_or_architecture_here}

package/pi-package/skills/research-codebase/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: research-codebase
+description: "Structured investigation of unfamiliar codebases"
+metadata:
+  installed-from: "incitaciones"
+---
+# Research Codebase
+
+Document and explain the codebase as it exists today.
+
+## Core Rule
+
+You are a documentarian, not an evaluator.
+
+## Procedure
+
+1. Understand the research question and clarify the focus if needed.
+2. Decompose the question into searchable components.
+3. Use `references/search-patterns.md` for search strategy and preferred commands.
+4. Read the identified files completely.
+5. Generate the report using `references/report-template.md`.
+
+## Rules
+
+- Describe what exists, where it exists, and how it works.
+- Provide file references for claims.
+- Show relationships between components.
+- Do not recommend improvements or refactors.

package/pi-package/skills/research-codebase/references/report-template.md

@@ -0,0 +1,75 @@
+```markdown
+# Research: [Topic]
+
+Date: [ISO date]
+Question: [Original research question]
+
+## Summary
+
+[2-3 paragraph high-level overview]
+
+## Architecture Overview
+
+[Describe the overall architecture]
+
+## Key Components
+
+### Component 1: [Name]
+
+Location: `path/to/file.ext:123`
+Purpose: [What it does]
+Used by: [What depends on this]
+Depends on: [What this depends on]
+
+How it works:
+[Step-by-step explanation]
+
+Key methods or functions:
+- `functionName()` (line 123): [What it does]
+
+## Data Flow
+
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+File references:
+- Step 1: `path/to/file.ext:123`
+- Step 2: `path/to/file.ext:456`
+
+## Patterns and Conventions
+
+- [Pattern]: [Purpose and evidence]
+
+## Configuration
+
+- Env vars: [If relevant]
+- Config files: [If relevant]
+
+## Error Handling
+
+- Error types: [If relevant]
+- Error handlers: [If relevant]
+
+## Testing
+
+- Test files: [If relevant]
+- Coverage or patterns: [If determinable]
+
+## Dependencies
+
+- External libraries: [If relevant]
+- Internal dependencies: [If relevant]
+
+## Entry Points
+
+1. `path/to/file.ext:123` - [Why it matters]
+
+## Related Documentation
+
+- [Doc path or README section]
+
+## Open Questions
+
+- [ ] [Anything still unclear]
+```

package/pi-package/skills/research-codebase/references/search-patterns.md

@@ -0,0 +1,27 @@
+## Research Search Patterns
+
+Use fast search tools first.
+
+```bash
+# Find auth-related files
+rg --files | rg "auth"
+
+# Search for authentication patterns
+rg -n "authenticate" .
+rg -n "login" .
+
+# Look for middleware or hooks
+rg -n "middleware" .
+rg -n "useAuth" .
+
+# Find configuration
+rg -n "auth" config .env.example
+```
+
+Research questions usually break down into:
+- Where the logic lives
+- What entry points exist
+- How state is managed
+- Where validation happens
+- How errors are handled
+- What the end-to-end flow looks like

package/pi-package/skills/research-documentation/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: research-documentation
+description: "Audit existing documentation or plan a new suite using advanced frameworks"
+metadata:
+  installed-from: "incitaciones"
+---
+# Research Documentation Architecture
+
+Audit the existing documentation or plan a new suite using the Unified Frameworks for Technical Information Architecture.
+
+## CRITICAL RULES
+
+1. ✅ **DO:** Categorize every document into exactly one Diátaxis quadrant.
+2. ✅ **DO:** Identify "Frankenbooks" (documents with mixed intent/quadrants).
+3. ✅ **DO:** Map the "Snowflake" progression from Core Assertion to granular topics.
+4. ✅ **DO:** Verify EPPO compliance (Does each page establish its own context?).
+5. ❌ **DO NOT:** Start writing content yet; focus on architecture and gaps.
+6. ❌ **DO NOT:** Suggest stylistic changes (focus on structural integrity).
+
+## Process
+
+### Step 1: Define the Scope
+
+[User will provide a path to a documentation directory or a project description.]
+- Identify the primary audience (Novice vs. Expert).
+- State the "Core Assertion" (The single-sentence value proposition).
+- **Legacy Conflict Resolution:** If existing documentation contains multiple, conflicting "hooks," identify the most impactful one or propose a synthesis for the new architecture.
+
+### Step 2: Audit Existing Content (if applicable)
+
+For each file in the directory, determine:
+- **Quadrant:** (Tutorial | How-to | Reference | Explanation).
+- **EPPO Status:** (Pass/Fail) Does it have standalone utility and context?
+- **Cognitive Load:** Are there "walls of words" or missing labels?
+
+### Step 3: Map the Snowflake Outline
+
+Expand the Core Assertion into a structural map:
+1. **Core Assertion:** [1 sentence]
+2. **Macro-Expansion:** [1 paragraph user journey]
+3. **Component List:** [The "characters" of the system]
+4. **Topic Matrix:** A list of proposed EPPO topics categorized by quadrant.
+
+### Step 4: Identify Gaps and Friction
+
+- **Quadrant Imbalance:** e.g., "Too much reference, not enough tutorials."
+- **Structural Plot-holes:** Where does the user journey break?
+- **AI-Readiness Gaps:** Missing `llms.txt`, poor semantic labeling.
+
+### Step 5: Final Research Report
+
+Output the audit/plan using the following template:
+
+```markdown
+# Documentation Research: [Project Name]
+
+## 1. Executive Summary & Core Assertion
+**Core Assertion:** [The one-sentence hook]
+**Status:** [Summary of current architecture health]
+
+## 2. Diátaxis Matrix
+| Quadrant | Existing Topics | Proposed/Missing Topics |
+| :--- | :--- | :--- |
+| **Tutorial** | | |
+| **How-to** | | |
+| **Reference** | | |
+| **Explanation** | | |
+
+## 3. Snowflake Structural Map
+- **Macro-Journey:** [Description]
+- **Key Components:** [List]
+
+## 4. EPPO & Cognitive Audit
+- **Frankenbooks Found:** [List of files with mixed intent]
+- **Context Gaps:** [Topics needing better orientation]
+
+## 5. AI-Readiness Assessment
+- [ ] `llms.txt` present?
+- [ ] Explicit semantic labeling for RAG?
+- [ ] MCP endpoints identified?
+
+## 6. Recommended Next Steps
+1. [Actionable structural change]
+2. [Actionable topic creation]
+```

package/pi-package/skills/research-review/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: research-review
+description: "Iterative review of research documents using Rule of 5"
+metadata:
+  installed-from: "incitaciones"
+---
+<!-- skill: research-review, version: 1.2.0, status: verified -->
+# Iterative Research Review
+
+Thoroughly review research documents for accuracy, completeness, and actionability using the Rule of 5 iterative refinement process.
+
+## Role
+You are a Senior Research Scientist. Your goal is to validate the integrity of findings, ensure all research questions are answered, and confirm that conclusions are supported by empirical evidence. You protect the project from making decisions based on outdated, inaccurate, or incomplete information.
+
+## Procedure
+
+1.  **Research Identification:**
+    *   Identify the research document to review. If none is provided, list available research files.
+    *   Read the document completely to understand the problem statement, methodology, and conclusions.
+
+2.  **Iterative Analysis (Rule of 5):**
+    Perform up to 5 passes, each with a specific focus. After each pass (starting with Pass 2), perform a **Convergence Check**.
+    *   **Pass 1: Accuracy & Sources** — Evidence-backed claims, source credibility/recency, and factual correctness of technical details.
+    *   **Pass 2: Completeness & Scope** — Unanswered research questions, gaps in analysis, and appropriate depth for the topic.
+    *   **Pass 3: Clarity & Structure** — Logical flow, clear definitions of terms, and consistent terminology.
+    *   **Pass 4: Actionability & Conclusions** — Clear takeaways, trade-offs articulated, and practical applicability to the project.
+    *   **Pass 5: Integration & Context** — Alignment with existing research, specs, and established project decisions.
+
+3.  **Convergence Check:**
+    *   Stop and report if **CONVERGED**: No new CRITICAL issues found AND new issue rate is <10% compared to the previous pass.
+    *   Otherwise, continue to the next pass.
+
+4.  **Verification (CRITICAL):**
+    *   **DO NOT** take research claims at face value. Use `read_file` or `grep_search` to cross-check any code references or architectural claims against the actual codebase.
+    *   Verify that referenced library versions or APIs are not deprecated or outdated.
+
+5.  **Final Synthesis:**
+    *   Produce a Final Report with a clear **Verdict** (READY | NEEDS_REVISION | NEEDS_MORE_RESEARCH) and a **Quality Assessment**.
+
+## Rules
+- **Verify Every Claim:** If a research document says "File X does Y", you must verify it before approving the research.
+- **Actionable Takeaways:** Research without a "next step" or recommendation is a HIGH-severity failure.
+- **Cite the Code:** All technical findings must reference specific files and, where possible, line ranges.
+- **Stop Early:** Do not force 5 stages if convergence is reached sooner.
+
+## References
+- **Templates:** Use `references/templates.md` for the exact output format of each pass and the final report.
+- **Criteria:** See `references/criteria.md` for detailed convergence rules and issue severity definitions.