incitaciones 0.1.0

package/content/distilled/plan-review/SKILL.md

@@ -0,0 +1,42 @@
+<!-- skill: plan-review, version: 1.2.0, status: verified -->
+# Iterative Plan Review
+
+Thoroughly review implementation plans for feasibility, completeness, and TDD alignment using the Rule of 5 iterative refinement process.
+
+## Role
+You are a Principal Systems Planner. Your goal is to identify risks, gaps, and technical contradictions in an implementation plan *before* code is written. You ensure that every plan is granular, verifiable, and follows a test-first methodology.
+
+## Procedure
+
+1.  **Plan Identification:**
+    *   Identify the plan to review. If none is provided, list available plans from `plans/`.
+    *   Read the plan completely to understand the overall architecture and phase structure.
+
+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: Feasibility & Risk** — Technical feasibility, external dependencies, unrealistic estimates, and missing rollback strategies.
+    *   **Pass 2: Completeness & Scope** — Missing phases, vague success criteria, and gaps between current and desired states.
+    *   **Pass 3: Spec & TDD Alignment** — Alignment with specification files and a clear test-first approach in every phase.
+    *   **Pass 4: Ordering & Dependencies** — Logical phase sequencing, parallelizable work, and independent verifiability of each phase.
+    *   **Pass 5: Clarity & Executability** — Specific file paths, concrete change descriptions, and unambiguous "done" definitions.
+
+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** assume the plan's technical claims are correct. Use `read_file` or `grep_search` to verify that any files the plan proposes to modify actually exist and that the proposed changes are technically viable within the current architecture.
+    *   Flag "We'll just..." statements that hide complexity as high-risk.
+
+5.  **Final Synthesis:**
+    *   Produce a Final Report with a clear **Verdict** (READY_TO_IMPLEMENT | NEEDS_REVISION | NEEDS_MORE_RESEARCH).
+
+## Rules
+- **Specific Fixes:** Do not just say "add detail"; specify *what* detail (e.g., "Add try-catch for JWT errors in Phase 2").
+- **Test-First Mandate:** Any phase without a corresponding verification/test step is a CRITICAL failure.
+- **Incremental Value:** Each phase must be independently verifiable and deployable (where possible).
+- **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.

package/content/distilled/plan-review/references/criteria.md

@@ -0,0 +1,51 @@
+# Plan Review Criteria
+
+Use these criteria to categorize findings and determine when the review process is complete.
+
+## Issue Severity Definitions
+
+| Severity | Criteria | Example Findings |
+| :--- | :--- | :--- |
+| **CRITICAL** | Blocks implementation or will cause catastrophic system failure. Violates TDD mandate (no test planned). | Feasibility contradiction, missing test for critical path, impossible phase order, hidden complexity ("We'll just..."). |
+| **HIGH** | Significantly impacts quality, security, or maintainability. High risk of regression. | Missing edge case handling, unmitigated security risk, vague success criteria, missing rollback plan. |
+| **MEDIUM** | Worth addressing to improve the plan but not blocking implementation. | Sub-optimal ordering, missing parallelization opportunities, vague file paths, minor dependency issues. |
+| **LOW** | Minor improvements, stylistic issues, or metadata gaps. | Typos in description, missing versioning, redundant phase commentary. |
+
+## Convergence Criteria
+
+**CONVERGED** if:
+- No new **CRITICAL** issues were found in the current pass AND
+- The number of new issues found is less than 10% compared to the previous pass AND
+- The estimated false positive rate is below 20%.
+
+**NEEDS_HUMAN** if:
+- After 5 passes, new **CRITICAL** issues are still being discovered.
+- The false positive rate exceeds 30%.
+- A major disagreement on architectural direction is identified.
+
+## Pass Focus Checklist
+
+### Pass 1: Feasibility & Risk
+- [ ] Is the proposed logic technically possible in the current codebase?
+- [ ] Are all external API/library dependencies accounted for?
+- [ ] Is there a rollback strategy for high-risk changes?
+
+### Pass 2: Completeness & Scope
+- [ ] Does the plan cover all affected files and components?
+- [ ] Are the success criteria for each phase clear and verifiable?
+- [ ] Is "Out of Scope" explicitly defined?
+
+### Pass 3: Spec & TDD Alignment
+- [ ] Does every implementation step have a corresponding test/verification step?
+- [ ] Are tests planned *before* implementation in the phase sequence?
+- [ ] Does the plan fulfill all requirements from the related specification?
+
+### Pass 4: Ordering & Dependencies
+- [ ] Are phases in a logical, executable order?
+- [ ] Are dependencies between phases clearly identified?
+- [ ] Is each phase independently verifiable?
+
+### Pass 5: Clarity & Executability
+- [ ] Are all file paths concrete and correct?
+- [ ] Could another engineer implement this without asking for more context?
+- [ ] Is it clear what "done" means for the overall plan?

package/content/distilled/plan-review/references/templates.md

@@ -0,0 +1,67 @@
+# Plan Review Templates
+
+Use these templates to provide a structured, high-signal report for each pass and the final verdict.
+
+## Pass Output Template
+
+Use this format for reporting results from any of the five passes.
+
+```markdown
+### PASS [N]: [Focus Area]
+
+#### Issues Found:
+[ID] [CRITICAL|HIGH|MEDIUM|LOW] - [Phase/Section]
+**Description:** [What's wrong or risky]
+**Evidence:** [Why this is a problem - cite codebase if relevant]
+**Recommendation:** [How to fix with specific technical guidance]
+
+[ID] ...
+```
+
+## Convergence Check Template
+
+Use this format after each pass (starting with Pass 2).
+
+```markdown
+**Convergence Check After Pass [N]:**
+
+1. New CRITICAL issues: [count]
+2. Total new issues this pass: [count]
+3. Total new issues previous pass: [count]
+4. Estimated false positive rate: [percentage]
+
+**Status:** [CONVERGED | ITERATE | NEEDS_HUMAN]
+```
+
+## Final Report Template
+
+After convergence or completing all 5 passes, provide this summary.
+
+```markdown
+# Plan Review Final Report
+
+**Plan:** plans/[filename].md | **Convergence:** Pass [N]
+
+## Summary Table
+| Severity | Count | Key Focus |
+| :--- | :--- | :--- |
+| **CRITICAL** | [count] | Feasibility / TDD Mandate |
+| **HIGH** | [count] | Completeness / Risks |
+| **MEDIUM** | [count] | Ordering / Dependencies |
+| **LOW** | [count] | Clarity / Formatting |
+
+## Top 3 Critical Findings
+1. **[ID] [Description]** - [Phase]
+   *   **Impact:** [Why this blocks implementation or causes failure]
+   *   **Fix:** [Specific actionable step]
+
+2. **[ID] ...**
+
+## Recommended Next Actions
+1. [Action 1 - specific and actionable]
+2. [Action 2 - specific and actionable]
+3. [Action 3 - specific and actionable]
+
+## Verdict: [READY_TO_IMPLEMENT | NEEDS_REVISION | NEEDS_MORE_RESEARCH]
+**Rationale:** [1-2 sentences explaining the verdict]
+```

package/content/distilled/pre-mortem.md

@@ -0,0 +1,10 @@
+Imagine it is [FUTURE DATE, e.g., six months from now]. The [PROJECT NAME] project has failed spectacularly. It was a complete disaster, resulting in [SPECIFIC NEGATIVE BUSINESS OUTCOME, e.g., 40% customer churn, a major security breach, a total budget overrun].
+
+You are the lead investigator writing the internal autopsy report. Your job is to uncover the root causes of the failure.
+
+Do not speculate on *if* it might fail. You must assume it *has* failed.
+
+Your task:
+1. Write a brief, 1-2 paragraph narrative describing how the failure unfolded.
+2. Based on that narrative, identify the top 3-5 root causes of the failure. For each root cause, trace it back to a specific decision, assumption, or action made in the plan *today*.
+3. Be specific and unflinching in your analysis. Your goal is to provide the team with the "prospective hindsight" needed to prevent this future from happening.

package/content/distilled/project-status-report.md

@@ -0,0 +1,124 @@
+# Evidence-Backed Project Status Report
+
+Create a concise, decision-grade project status report for the requested project, workstream, or agent run.
+
+## Inputs
+
+If missing, ask for the minimum context before drafting:
+- project/workstream name;
+- reporting period;
+- audience: executive, engineering, product, client/sponsor, or mixed;
+- available evidence sources: tickets, PRs, commits, CI/CD, incidents, metrics, docs, risk logs, decision logs, traces, or notes;
+- baseline commitments, if any: scope, date, budget, quality, OKR, milestone, or SOW.
+
+## Rules
+
+- Prefer evidence-linked claims over narrative claims.
+- Separate facts from interpretation.
+- Mark unknowns explicitly; do not invent missing evidence.
+- Link to access-controlled evidence; do not paste secrets, credentials, personal data, private code, sensitive prompts, or sensitive trace content.
+- If no safe evidence link exists, summarize only non-sensitive metadata, such as artifact ID, trace ID, run time, status, and redacted outcome.
+- Never report Green without objective supporting evidence.
+- If evidence conflicts, report dimension-specific status before assigning overall RAG.
+- Separate “blocked” from “at risk.” Blocked means work cannot proceed without external action; at risk means the forecast is threatened.
+- Separate “tests passed” from “accepted,” “merged,” “deployed,” or “independently verified.”
+- Every Amber or Red item must include owner, mitigation, and next review date; if any field is unknown, mark it unknown and list it as a decision/ask.
+
+## Status Scale
+
+Use organization-specific thresholds when available. Otherwise:
+
+- **Unknown / Unrated:** no agreed baseline exists, evidence is insufficient, or discovery work has not established meaningful thresholds.
+- **Green:** within agreed tolerance; no unresolved blocker threatens a key commitment; evidence supports the forecast.
+- **Amber:** material variance or dependency risk exists, but there is a credible recovery plan with owner and date.
+- **Red:** a critical objective, milestone, safety requirement, compliance requirement, or budget/schedule constraint is no longer under control, or no credible recovery plan exists.
+
+## Procedure
+
+1. Identify audience and decision the report supports.
+2. Gather/inspect available evidence before drafting.
+3. Compare baseline vs current state.
+4. Assign dimension-specific status when useful: scope, schedule, quality, reliability, cost, risk, governance.
+5. Assign overall status only after reviewing evidence.
+6. Summarize completed outcomes, current work, forecast changes, blockers, risks, dependencies, and decisions needed.
+7. Include agentic AI evidence when applicable.
+8. Keep executive summary short; put trace-level/ticket-level detail behind links or appendices.
+9. For mixed audiences, put the executive summary first and move technical detail to evidence links or an appendix.
+
+## Output Template
+
+Use only applicable sections. Omit empty sections.
+
+```markdown
+# Project Status: <project name>
+
+Reporting period: <date range>
+Owner / DRI: <name or unknown>
+Audience: <executive | engineering | product | client | mixed>
+Overall status: <Unknown / Unrated | Green | Amber | Red>
+Trend: <Improving | Stable | Worsening | Unknown>
+Confidence: <High | Medium | Low | Unknown>
+
+## Executive Summary
+- <1-3 bullets on outcome, forecast, and most important risk/ask>
+
+## What Changed Since Last Report
+- Completed: <evidence-linked outcomes, not activity lists>
+- In progress: <current work and expected completion>
+- Not completed as planned: <variance and reason>
+
+## Evidence
+- Tickets / roadmap items: <links or IDs>
+- PRs / commits / releases: <links or IDs>
+- CI / test / deployment status: <links or summary>
+- Metrics: <DORA, flow, EVM, SLO, OKR, or domain-specific metrics>
+- Agent traces, if applicable: <trace IDs / run IDs; link to access-controlled evidence>
+
+## Forecast and Variance
+- Baseline commitment: <scope/date/budget/quality target>
+- Current forecast: <updated forecast>
+- Variance: <numeric or concrete difference>
+- Reason for variance: <root cause or current best explanation>
+
+## Risks, Issues, Blockers, Dependencies
+Use one row per risk, issue, blocker, or dependency.
+
+| Type | Description | Impact | Owner | Due / review date | Mitigation / ask |
+|---|---|---|---|---|---|
+| Risk/Issue/Blocker/Dependency |  |  |  |  |  |
+
+## Decisions
+- Decisions made this period: <decision + rationale + link>
+- Decisions needed: <decision + owner + deadline + consequence of no decision>
+
+## Next Commitments
+- By next report: <specific promised outcomes>
+- Next 2-4 weeks: <look-ahead commitments and dependencies>
+
+## Agentic AI Evidence, if applicable
+Omit this section when no agentic AI was used.
+
+Minimum evidence:
+- Agent/model/prompt/tool versions: <versions>
+- Autonomy level: <manual | assisted | supervised autonomous | autonomous with audit>
+- Human checkpoints: <approvals, overrides, rejected actions>
+- Verification state: <generated | tested | independently verified | merged | deployed>
+- Trace/provenance: <trace IDs, commit SHA, PR, build, deployment>
+- Cost/latency: <tokens, cost, runtime if material>
+- Safety/policy exceptions: <none or details>
+
+Extended governance evidence, when risk or regulation warrants:
+- Retrieved context and data sources
+- Detailed tool-call sequence / span tree
+- Independent evaluation results
+- SBOM, signatures, or release provenance
+- Red-team, abuse-test, or policy-review notes
+```
+
+## Quality Bar
+
+Before finalizing, verify:
+- The report answers: what changed, what is next, what is blocked, and what decision/help is needed.
+- Every nontrivial claim has evidence or is marked unknown.
+- Amber/Red items include owner, mitigation, and next review date, or unknown fields are marked and converted into decisions/asks.
+- The audience can act on the report without asking for a second status meeting.

package/content/distilled/pwa-accessibility-review.md

@@ -0,0 +1,81 @@
+# PWA Accessibility & Reliability Review for Micro-Merchants
+
+Act as a Senior Mobile Web Performance and Digital Inclusion Architect. Review the provided [INPUT] (source code, service worker, or architecture document) for a PWA targeting non-technical micro-merchants on entry-level Android devices (2-4GB RAM) with volatile connectivity. Evaluate across four domains. Flag every violation with domain, criterion, file location, and a concrete fix.
+
+## Domain 1: Cognitive Usability & WCAG Accessibility
+
+### 1.1 Linguistic Audit
+- Flag technical jargon in user-facing strings ("sync," "cache," "authenticate," "fetch," "timeout," "session," "token," "retry") and suggest plain-language replacements ("saving," "saved data," "log in," "loading," "taking too long").
+
+### 1.2 Interaction Target Sizing
+- All interactive elements must have minimum **44x44px** touch area with minimum **8px** gap between adjacent targets.
+
+### 1.3 Visual Hierarchy & Progressive Disclosure
+- Navigation depth maximum **2 layers**. Text/background contrast must meet **WCAG AA** (4.5:1 normal, 3:1 large). Every icon must have a paired text label or `aria-label`. Primary action must dominate each screen.
+
+### 1.4 Feedback & Error Handling
+- Every async operation needs immediate visual feedback (button disable, spinner, success/failure state). Error messages must be empathetic and prescriptive — no error codes or technical language. Explicit Undo/Back/Cancel for destructive or financial actions. Multi-sensory confirmation (visual + haptic/audio) for payment finalization.
+
+## Domain 2: Offline Architecture & Reliability
+
+### 2.1 Storage Separation
+- **Cache API** strictly for static shell assets (HTML, CSS, JS, fonts, images). **IndexedDB** (via Dexie.js/localForage) strictly for mutable data (transactions, carts, inventory). Flag `localStorage` for structured data. Flag mutable state in Cache API.
+
+### 2.2 Caching Strategy Validation
+- **CacheFirst** for static shell. **NetworkFirst** (cache fallback) for dynamic data. **StaleWhileRevalidate** for catalogs/images/pricing. Workbox or equivalent required. Service worker `activate` must `caches.delete()` old versions.
+
+### 2.3 iOS Resilience
+- Detect iOS UA + `navigator.standalone`. Render "Add to Home Screen" overlay if not standalone. Push handlers must use `event.waitUntil(self.registration.showNotification(...))` (3 silent pushes = permanent subscription kill). `Notification.requestPermission()` only on user gesture.
+
+### 2.4 Background Sync & Data Integrity
+- `sync.register()` for offline action queuing. `sync` event listener replays on connectivity. IndexedDB queries must use **cursor-based pagination** (unbounded loads trigger OOM on 2GB devices). Monitor quota via `navigator.storage.estimate()`.
+
+## Domain 3: Hardware Optimization & Main Thread
+
+### 3.1 Main Thread Blocking
+- Lists >50 items require **virtual scrolling**. Flag patterns likely to produce long tasks (>50ms): large synchronous loops, blocking I/O, undeferred heavy computation.
+
+### 3.2 Execution Yielding
+- Defer non-critical scripts (analytics, telemetry) until after first interaction via `requestIdleCallback`, `scheduler.yield()`, `setTimeout(0)`, or dynamic `import()`. Flag synchronous third-party scripts in critical path.
+
+### 3.3 Bundle & Rendering
+- Flag DOM >1500 nodes (warning) or >3000 (critical). Verify code splitting — initial bundle for first screen only. Flag hydration that blocks input responsiveness.
+
+## Domain 4: Security & Data Integrity
+
+### 4.1 Data Leakage
+- Sensitive views (login, password reset) excluded from SW cache via `Cache-Control: no-store`. No tokens/PII in Cache API.
+
+### 4.2 Payload Integrity
+- Offline IndexedDB payloads **cryptographically signed** (HMAC) before Background Sync upload. Server validates signature.
+
+### 4.3 CSP & Service Worker Protection
+- Strict `Content-Security-Policy` restricting `script-src`, `worker-src`, `connect-src`. No `unsafe-inline`/`unsafe-eval`. HTTPS enforced for all SW registrations and sync endpoints.
+
+## Output Format
+
+Per domain:
+```
+## Domain N: [Name]
+Status: PASS | FAIL | PARTIAL
+### Violations
+[DOM-N.M] [CRITICAL|HIGH|MEDIUM|LOW] — [file:line]
+  Finding: [What's wrong]
+  Fix: [Actionable remediation]
+### Passes
+- [What was correct]
+```
+
+Conclude with:
+```
+## Summary
+- Domain 1 (Usability): [PASS|FAIL|PARTIAL]
+- Domain 2 (Offline): [PASS|FAIL|PARTIAL]
+- Domain 3 (Performance): [PASS|FAIL|PARTIAL]
+- Domain 4 (Security): [PASS|FAIL|PARTIAL]
+Overall: [READY | NEEDS_REVISION | NOT_READY]
+Top 3 Critical Fixes: [list]
+```
+
+[INPUT]:
+{provide_code_or_architecture_here}

package/content/distilled/rca-diagnostician/SKILL.md

@@ -0,0 +1,30 @@
+# RCA Diagnostician
+
+Conduct or evaluate a root cause analysis using cross-disciplinary principles. Moves from symptom to systemic cause, selects appropriate methods, applies cognitive bias countermeasures, and produces corrective actions ranked by strength.
+
+## Setup
+
+- If an incident description or RCA report is provided, read it completely.
+- If no input is provided, ask what incident or failure to investigate.
+- Determine the mode: INVESTIGATE (new RCA) or EVALUATE (review existing report).
+
+## Procedure
+
+1. **Scope the problem.** Define WHAT/WHERE/WHEN/SEVERITY and the counterfactual. Use `references/problem-definition.md`.
+2. **Collect and map evidence.** Inventory sources, assess sufficiency (3-stream minimum), reconstruct the timeline. Use `references/evidence-timeline.md`.
+3. **Generate and test hypotheses.** Produce candidates at mechanism, process, and organizational levels. Select the appropriate RCA method for the domain. Use `references/hypothesis-methods.md`.
+4. **Apply bias countermeasures.** Check for confirmation bias, blame displacement, correlation-causation overreach, and early closure. Use `references/bias-countermeasures.md`.
+5. **Define corrective actions.** Rank by strength (strong/intermediate/weak). Require at least one strong action. Define verification metrics. Use `references/action-hierarchy.md`.
+6. **Evaluate rigor.** Apply the minimum viable rigor checklist. If AI tools were used, apply the AI governance checklist. Use `references/rigor-checklist.md`.
+7. **Produce the final report.** Use `references/report-template.md`.
+
+For EVALUATE mode: read the existing report, extract the problem definition (step 1), then skip to step 6 (rigor evaluation), then produce the report. If the existing report is too thin for meaningful evaluation (fewer than 3 of 9 rigor criteria can be assessed), recommend switching to INVESTIGATE mode instead.
+
+## Rules
+
+- Never promote correlation to causation without a causal model or explicit uncertainty.
+- Never accept a single-cause narrative without testing alternatives.
+- Never recommend only weak actions (retraining, reminders) when the system predictably creates the error.
+- Every action must have a verification metric and monitoring period.
+- Reference exact evidence from the input. Do not fabricate findings.
+- This diagnostic is advisory — do not implement fixes during this session.

package/content/distilled/rca-diagnostician/references/action-hierarchy.md

@@ -0,0 +1,77 @@
+## Corrective Action Hierarchy and Verification
+
+### Action Strength Classification
+
+Rank every proposed corrective action by its ability to change the system:
+
+**Strong (system redesign):**
+- Architectural changes that eliminate the failure mode
+- Forcing functions and interlocks (make the error physically/logically impossible)
+- Automation of detection or prevention (the system catches or prevents without human action)
+- Interface redesign that removes the ambiguity or error pathway
+- Examples: circuit breakers, type-safe interfaces, automated rollback triggers, equipment redesign, workflow interlocks
+
+**Intermediate (enhanced controls):**
+- Improved monitoring and alerting (reduces detection time but doesn't prevent)
+- Checklists and standardized procedures (reduces variation but depends on compliance)
+- Staffing changes (reduces workload-driven errors but doesn't eliminate the mechanism)
+- Process redesign (changes the workflow but doesn't add forcing functions)
+- Examples: new dashboard alerts, pre-deployment checklists, on-call rotation changes, peer review gates
+
+**Weak (awareness-only):**
+- Retraining or education
+- Policy memos and reminders
+- "Be more careful" directives
+- Documentation updates without verification that they are read or followed
+- Examples: email reminders, updated wiki pages, all-hands announcements, annual training modules
+
+### Minimum Strong Action Requirement
+
+**Every RCA must include at least one strong action.** If only intermediate or weak actions are proposed:
+
+1. Flag this explicitly: "Action portfolio contains no strong actions"
+2. Describe what system change would be needed — even if it requires resources, authority, or timeline the team doesn't currently have
+3. Recommend escalation to the authority level that can approve the strong action
+4. Document the risk accepted by proceeding with only intermediate/weak actions
+
+### Verification Plan
+
+For each action, define:
+
+| Element | Required |
+|---------|----------|
+| **Verification metric** | What measurable outcome confirms the action reduced risk? |
+| **Monitoring period** | How long must the metric be tracked? (Minimum: 2x the mean time between previous occurrences. For novel incidents without recurrence history, use 90 days or one full operational cycle, whichever is longer.) |
+| **Owner** | Named person accountable for implementation and verification |
+| **Deadline** | Implementation completion date |
+| **Escalation path** | What happens if the metric does not improve within the monitoring period? |
+
+### Learning Loop
+
+Identify how findings feed back into the organization:
+
+- Standards or specifications to update
+- Training content to modify
+- Design review criteria to add
+- Monitoring and alerting to change
+- Audit or compliance checks to introduce
+
+### Output
+
+```text
+## Corrective Actions
+
+| # | Root cause addressed | 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 requirement: [MET | NOT MET — escalation needed]
+
+## Learning Loop
+
+- Standards to update: [list]
+- Training to modify: [list]
+- Monitoring to add/change: [list]
+- Design reviews to inform: [list]
+```

package/content/distilled/rca-diagnostician/references/bias-countermeasures.md

@@ -0,0 +1,64 @@
+## Cognitive Bias Countermeasures
+
+RCA fails more often from cognitive and organizational barriers than from lack of method. Apply these checks explicitly during hypothesis generation and evaluation.
+
+### Check 1: Confirmation Bias
+
+Question: Did you actively seek disconfirming evidence for your leading hypothesis?
+
+Red flags:
+- All cited evidence supports one narrative
+- Alternative hypotheses were listed but not seriously tested
+- Disconfirming data was explained away rather than weighted
+- The investigation stopped at the first plausible story
+
+Test: Can you name specific evidence that would weaken your leading hypothesis? If you cannot, the investigation has early-closure risk.
+
+### Check 2: Blame Displacement
+
+Question: Are you attributing to individuals what the system predictably creates?
+
+Red flags:
+- Root cause is stated as "operator error," "didn't follow procedure," or "lack of training"
+- No analysis of why the system allowed or encouraged the error
+- Corrective actions are person-only (retraining, disciplinary action, reminders)
+- The same error has occurred before with different individuals
+
+Test: If you replaced this person with a competent peer, would the system still create conditions for the same failure? If YES, the system is the root cause, not the individual.
+
+### Check 3: Correlation-Causation Overreach
+
+Question: Are you promoting a statistical association to a causal claim without a mechanistic explanation?
+
+Red flags:
+- "X happened before Y, therefore X caused Y" (temporal precedence alone)
+- Pattern found in data without explanation of how X produces Y
+- Confounding variables not considered (something else changed simultaneously)
+- AI/ML tool surfaced a correlation and it was adopted as a root cause
+
+Test: Can you explain the mechanism by which X causes Y? Can you identify confounders that might explain the association? If not, label this as "candidate association, not confirmed cause."
+
+### Check 4: Early Closure
+
+Question: Did the investigation stop at an organizationally convenient explanation?
+
+Red flags:
+- Only one root cause identified for a complex failure
+- Investigation ended after a single pass of "5 Whys" without cross-checking
+- The root cause conveniently avoids implicating leadership decisions, resource allocation, or organizational culture
+- Timeline reconstruction was skipped or abbreviated
+
+Test: Ask "who benefits from this being the root cause?" If the answer is "leadership" or "the investigating team," apply additional scrutiny.
+
+### Output
+
+```text
+## Bias Check
+
+- Confirmation bias: [CLEAR | FLAG — describe concern]
+- Blame displacement: [CLEAR | FLAG — describe concern]
+- Correlation-causation: [CLEAR | FLAG — describe concern]
+- Early closure: [CLEAR | FLAG — describe concern]
+
+Countermeasure actions taken: [what you did to mitigate flagged biases]
+```

package/content/distilled/rca-diagnostician/references/evidence-timeline.md

@@ -0,0 +1,49 @@
+## Evidence Collection and Timeline Reconstruction
+
+Map what happened before hypothesizing why.
+
+### Evidence Inventory
+
+Classify each source into one of four types:
+
+| Type | Examples | Reliability notes |
+|------|----------|-------------------|
+| **Records** | Logs, metrics, charts, audit trails | Machine-generated; check for gaps and clock skew |
+| **Direct observation** | Inspections, screenshots, reproductions | Strongest when captured during/near the event |
+| **Testimony** | Interviews, incident comms, retrospective accounts | Subject to hindsight bias and memory distortion |
+| **Artifacts** | Config changes, code diffs, design docs, process maps | Check timestamps; distinguish planned vs. actual |
+
+### Three-Stream Sufficiency Test
+
+Do you have at least three independent evidence streams (e.g., logs + interviews + config history)? If not:
+
+- Flag the gap explicitly
+- Recommend what to gather before proceeding
+- Note which hypotheses cannot be tested with current evidence
+- Mark all subsequent outputs as **PROVISIONAL** until evidence gaps are filled — this must carry through to the rigor checklist and final report
+
+### Timeline Construction
+
+Build chronologically from last known normal state through detection and resolution:
+
+- **Decision points**: who decided what, with what information available at the time
+- **Environmental context**: workload, staffing, concurrent changes, external events
+- **Hindsight compression guard**: record what was known vs. not known at each point — do not project post-event knowledge backward
+
+### Output
+
+```text
+## Evidence Inventory
+
+| Source | Type | Reliability | Key facts |
+|--------|------|-------------|-----------|
+| [source] | [record/observation/testimony/artifact] | [high/medium/low] | [what it tells us] |
+
+Evidence sufficiency: [MET — 3+ streams | GAP — need X]
+
+## Timeline
+
+| Time | Event | Source | Notes |
+|------|-------|--------|-------|
+| [when] | [what happened] | [evidence source] | [context] |
+```

package/content/distilled/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]
+```