incitaciones 0.1.0

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

@@ -0,0 +1,73 @@
+# Research 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] - [Section/Paragraph]
+**Description:** [What's inaccurate, incomplete, or ambiguous]
+**Evidence:** [Why this is a problem - cite source or codebase]
+**Recommendation:** [How to improve with specific research or fix]
+
+[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
+# Research Review Final Report
+
+**Research:** [path/to/research.md] | **Convergence:** Pass [N]
+
+## Summary Table
+| Severity | Count | Key Focus |
+| :--- | :--- | :--- |
+| **CRITICAL** | [count] | Factual Accuracy / Evidence |
+| **HIGH** | [count] | Analysis Gaps / Conclusions |
+| **MEDIUM** | [count] | Actionability / Clarity |
+| **LOW** | [count] | Metadata / Flow |
+
+## Research Quality Assessment
+- **Accuracy**: [Excellent|Good|Fair|Poor] - [brief comment]
+- **Completeness**: [Excellent|Good|Fair|Poor] - [brief comment]
+- **Actionability**: [Excellent|Good|Fair|Poor] - [brief comment]
+- **Clarity**: [Excellent|Good|Fair|Poor] - [brief comment]
+
+## Top 3 Critical Findings
+1. **[ID] [Description]** - [Section]
+   *   **Impact:** [Why this leads to bad decisions or is factually wrong]
+   *   **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 | NEEDS_REVISION | NEEDS_MORE_RESEARCH]
+**Rationale:** [1-2 sentences explaining the verdict based on evidence quality]
+```

package/content/distilled/resonant-refactor.md

@@ -0,0 +1,45 @@
+<!-- Full version: content/prompt-workflow-resonant-refactor.md -->
+You are a Refactoring Specialist. Perform precise, verified, reversible changes. Do NOT touch any files before the human approves the plan.
+
+**TASK**: Refactor to use [DESCRIBE ABSTRACTION/CHANGE]. Target: [FILES OR "discover via analysis"]
+
+**Phase 1 — Impact Analysis** (no code changes yet):
+- Find all usage sites via grep/search
+- List every file that will be modified
+- Predict side effects (API changes, type changes, edge cases)
+- Assign risk: Low / Medium / High with one-sentence justification
+
+**Phase 2 — Shadow Test** (no code changes yet):
+- Identify existing tests covering the changed code
+- Run them NOW to establish a baseline — if any fail before changes, STOP and report
+- If tests are known flaky, run 3 times; record baseline failure rate; only rollback if execution exceeds baseline
+- If no tests: write a minimal manual verification checklist
+
+**Phase 3 — Human Latch** (REQUIRED STOP):
+Output this block and wait for "APPROVE":
+
+---
+REFACTOR PLAN — APPROVAL REQUIRED
+Abstraction: [name]
+Files to modify: [N files — list]
+Impact: [what changes, what stays]
+Risk: [Low/Med/High] — [justification]
+Verification: [test command or manual steps]
+Rollback: `git reset --hard HEAD` restores all changes
+
+Reply APPROVE to begin.
+---
+
+**Phase 4 — Atomic Execution** (after APPROVE):
+Do NOT commit or stage files during execution — working tree only. This ensures rollback covers all changes.
+
+For each file: apply change → run verification → report "✓ [file] — passed" or "✗ [file] — [error]"
+
+Self-correction: on failure, attempt fix up to 3 times. If all 3 fail: run `git reset --hard HEAD`, report the error, stop.
+
+**Phase 5 — Quality Gates**:
+- Run linter on modified files
+- Run full test suite
+- Add docstring to new abstraction: what it does, why it exists, parameters
+
+**Completion Report**: files modified, verification pass/fail, linter pass/fail, tests pass/fail, abstraction documented, recommended next step.

package/content/distilled/resume-handoff/SKILL.md

@@ -0,0 +1,19 @@
+# Resume from Handoff
+
+Resume work from a handoff document through analysis and verification.
+
+## Procedure
+
+1. Locate the handoff file.
+2. Read it completely.
+3. Extract current status, critical files, learnings, open questions, and next steps.
+4. Verify how the repository changed since the handoff.
+5. Read the referenced critical files.
+6. Present the current situation using `references/analysis-template.md`.
+7. Wait for confirmation before starting new work.
+
+## Rules
+
+- Always verify the handoff against the current codebase.
+- Treat stale handoffs as possibly inaccurate.
+- Preserve the original priorities unless the current repository invalidates them.

package/content/distilled/resume-handoff/references/analysis-template.md

@@ -0,0 +1,40 @@
+```text
+I've analyzed the handoff from [date]. Here's the current situation:
+
+## Original Context
+[Summary of what was being worked on]
+
+## Task Status Review
+
+Completed:
+- [x] [Task] - VERIFIED: [Current status]
+
+In Progress:
+- [ ] [Task] - STATUS: [Current state]
+
+Planned:
+- [ ] [Next task]
+
+## Changes Since Handoff
+
+Commits since handoff:
+- [Commit summary]
+
+Impact:
+[How the current state affects the original plan]
+
+## Key Learnings Still Applicable
+
+1. [Learning] - [Why it still applies or not]
+
+## Questions Needing Resolution
+
+- [ ] [Question]
+
+## Recommended Next Action
+
+Priority 1: [Action]
+- Reason: [Why]
+- Files: [What to read or change]
+- Approach: [How to proceed]
+```

package/content/distilled/resume-handoff/references/locating.md

@@ -0,0 +1,12 @@
+## Locating a Handoff
+
+Examples:
+
+```bash
+# List recent handoffs
+ls -lt handoffs/ | head -10
+
+# Find handoffs for a specific issue
+ls handoffs/*issue-123* | sort -r | head -1
+rg -n "issue: issue-123" handoffs/*.md
+```

package/content/distilled/review-documentation.md

@@ -0,0 +1,44 @@
+# Review Documentation Quality
+
+Perform a Rule of 5 review of the documentation using the Unified Frameworks for Technical Information Architecture.
+
+## REVIEW PROCESS
+
+Perform 5 iterative passes, checking for convergence after each pass (starting with pass 2).
+
+### PASS 1: Diátaxis & Intent
+- **Goal:** Does this topic have a single, clear intent?
+- **Checks:** Is it a Tutorial, How-to, Reference, or Explanation? Are there "leaked" intents? (e.g., too much theory in a Tutorial).
+- **Issue Prefix:** [INTENT-001]
+
+### PASS 2: EPPO & Standalone Utility
+- **Goal:** Can a "foraging" reader land here and succeed?
+- **Checks:** Are context and prerequisites established in the first two sentences? Does it rely on "previous chapter" knowledge without links?
+- **Issue Prefix:** [EPPO-001]
+
+### PASS 3: Cognitive Scannability (Info Mapping)
+- **Goal:** Can the reader scan the page in <10 seconds and find the key answer?
+- **Checks:** Are **labels** (descriptive headers) used for every 2-3 paragraphs? Are paragraphs chunked into small units? Are there tables/lists for complex data?
+- **Issue Prefix:** [SCAN-001]
+
+### PASS 4: Accuracy, "Whole Game" & Fail-States
+- **Goal:** Is the content technically sound and resilient?
+- **Checks:** Are the code snippets/math verified? Does it show the "Whole Game" (complete result)? Are common errors (fail-states) documented? In tutorials, is the **Martini Glass** pattern followed (context → exploration)?
+- **Issue Prefix:** [ACC-001]
+
+### PASS 5: Excellence & AI-Readiness
+- **Goal:** Is it production-ready and optimized for AI agents?
+- **Checks:** Is there a TL;DR for LLMs? Are headers semantically unique for RAG? Is the **Answer First** (Pyramid Principle) located in the TL;DR and first paragraph?
+- **Issue Prefix:** [EXCL-001]
+
+## Convergence Check
+After each pass (starting with pass 2), report:
+- Total new issues found.
+- Estimated "Signal-to-Noise" ratio.
+- Convergence status: (CONVERGED | CONTINUE).
+
+## Final Report Format
+- **Total Issues by Severity** (Critical | High | Medium | Low).
+- **Top 3 Findings.**
+- **Verdict:** (Ready | Needs Revision | Needs Rework).
+- **Rationale.**

package/content/distilled/rigidity-diagnostician.md

@@ -0,0 +1,70 @@
+<!-- Full version: content/prompt-task-rigidity-diagnostician.md -->
+You are a Software Architecture Analyst. Diagnose structural rigidity — cascading change resistance caused by excessive coupling, inappropriate inheritance, and OCP violations — and map each finding to a composition-based remediation pattern. Do NOT modify any files — advisory only.
+
+**GUARD:** Do not apply to greenfield projects, inter-service rigidity (API contracts between microservices), or languages with no polymorphism mechanism (no interfaces, abstract types, first-class functions, function pointers, or equivalent). Do not recommend composition patterns for stable code with no historical change pressure — flag as premature abstraction risk instead.
+
+**INPUT**
+- Target files/directory: [SPECIFY]
+- High-churn files (optional): [git log output OR "none"]
+- Architecture reference (optional): [AGENTS.md rules OR "none"]
+- Paradigm (optional): [OOP / FP / Mixed — or "infer"]
+
+**PROTOCOL (Six-Step Pipeline)**
+
+Step 1 — Detect Code Smells: Read all files. Identify rigidity signals:
+- God Class / Large File (High): many responsibilities, many dependencies
+- Long Methods / Excessive Parameters (High): 50+ lines, 5+ params (adjust for language norms — Go option structs, Rust generics are not inherently problematic)
+- Feature Envy (High): methods accessing another object's data more than their own
+- Duplicated Conditional Logic (High): same switch/if-else in multiple locations
+- Fragile Base Class (High): deep inheritance (3+ levels) where base changes break subclasses
+- Duplicated Code (Medium): structurally similar blocks with minor variations
+- Shotgun Surgery (Medium): single conceptual change requires edits across many files
+- Lazy Classes (Low): classes doing too little to justify their complexity cost
+Note file, line range, and description for each.
+
+Step 2 — Analyze Coupling: For each smell, assess coupling type:
+- Static: direct `new`, concrete types in signatures
+- Inheritance: deep extends/inherits chains, override dependencies
+- Temporal: required call ordering
+- Semantic: no code dependency but must change together
+- Data: shared mutable state, globals, singletons
+Rate severity: Isolated (local) / Moderate (2-3 files) / Cascading (4+ files).
+
+Step 3 — Identify Axes of Change: Ask: "Can this module be replaced without changing others?" Categorize via DDD strategic design's 3 Buckets (Evans/Vernon):
+- Core Domain (high volatility → OCP critical)
+- Supporting Subdomain (moderate → composition beneficial)
+- Generic Component (low → concrete implementations acceptable)
+If git churn data provided, cross-reference: tightly coupled + frequently modified = highest priority.
+
+Step 4 — Diagnose OCP Violations: Check for:
+1. Switch/if-else chains branching on type — new variant requires modifying existing code
+2. Repeated methods of identical structure — new variant demands new method
+3. Hardcoded conditional logic — business rules embedded in execution flow
+4. Data-driven rigidity — adding peer entity requires source modification
+Flag whether violation is at a volatile axis (high priority) or stable area (lower — avoid premature abstraction).
+
+Step 5 — Map to Composition Pattern:
+- Switch on type → **Strategy**: interface + concrete implementations per branch
+- Subclass explosion → **Decorator**: composable layers sharing same interface
+- Lifecycle state conditionals → **State**: state interface + concrete state classes
+- Part-whole hierarchies → **Composite**: tree with shared interface
+- Rigid step ordering → **Pipeline/Chain of Responsibility**: composable middleware
+- Deep inheritance → **Composition refactoring** (4-step): analyze → extract interface → inject → flatten
+- Repeated method shapes → **Data-driven config**: config objects + delegates
+
+FP equivalents: Strategy→higher-order function, State→sum types+pattern matching, Decorator→function composition, Config→first-class functions in data structures.
+
+Step 6 — Prioritize: Score = Coupling Severity (Cascading=3, Moderate=2, Isolated=1) × Change Frequency (High=3, Moderate=2, Stable=1) × Axis Volatility (Core=3, Supporting=2, Generic=1). If no git data, estimate churn from structural signals: TODO/FIXME density, feature-flag conditionals, version-specific branches suggest high churn; stable utilities with no branching suggest low. Sequence so foundational abstractions come first, high-priority unblocking items lead, each step is independently deployable.
+
+**OUTPUT**
+
+Summary table:
+| Location | Code Smell | Coupling Type | OCP Violation | Composition Pattern | Priority |
+
+If multiple smells share a root cause, consolidate. Then per finding: smell (files, lines), coupling analysis (type + blast radius), axis of change (bucket + volatility), OCP violation (how modification is forced), recommended pattern (interface name, key classes, injection point — no full implementation), refactoring sequence (safe steps, never change behavior and structure simultaneously), success signals (fewer files per feature, switches eliminated, new variants via new classes only).
+
+Needs Human Review: list ambiguous cases — intentional tight coupling (performance), potential speculative generality, composition trade-offs that may not justify flexibility, inheritance that models genuine stable taxonomy.
+
+If no signals found: "No rigidity signals found. Codebase exhibits clean separation and appropriate composition at identified axes of change." Do not fabricate findings.
+
+Stop when all files analyzed. Do not modify anything.

package/content/distilled/rule-of-5-universal/SKILL.md

@@ -0,0 +1,26 @@
+# Universal Rule of 5 Review
+
+Review any intellectual artifact (code, plans, research, issues, specs, documentation) using Steve Yegge's 5-stage iterative editorial refinement process until convergence.
+
+## Core Philosophy
+"Breadth-first exploration, then editorial passes." Don't aim for perfection in early stages. Each stage builds on insights from previous stages.
+
+## Procedure
+1.  **Stage 1: DRAFT** - Evaluate overall shape and sound approach. Focus on architecture, organization, and scope.
+2.  **Stage 2: CORRECTNESS** - Identify errors, bugs, or logical flaws. Check for convergence.
+3.  **Stage 3: CLARITY** - Ensure comprehensibility for the intended audience. Check for convergence.
+4.  **Stage 4: EDGE CASES** - Handle boundary conditions and unusual scenarios. Check for convergence.
+5.  **Stage 5: EXCELLENCE** - Final polish for production quality and pride.
+6.  **Final Report** - Synthesize findings and provide a final verdict.
+
+## Rules
+- **Progressive Build:** Each stage must build on previous findings.
+- **Specificity:** Reference exact locations (file:line, section, paragraph).
+- **Actionability:** Suggest specific solutions, don't just identify problems.
+- **Validation:** Confirm issues exist; do not flag "potential" issues without evidence.
+- **Early Stop:** Stop if convergence criteria are met before Stage 5.
+
+## References
+- **Templates:** Use `references/templates.md` for the exact output format of each stage and the final report.
+- **Criteria:** Refer to `references/criteria.md` for convergence and escalation rules.
+- **Examples:** (Optional) See `references/examples.md` for domain-specific review examples.

package/content/distilled/rule-of-5-universal/references/criteria.md

@@ -0,0 +1,34 @@
+# Rule of 5 Convergence & Escalation Criteria
+
+## Convergence Check
+Perform this check after Stage 2, Stage 3, and Stage 4.
+
+```
+New CRITICAL issues: [count]
+Total new issues: [count]
+New issues vs Previous Stage: [percentage change]
+Status: [CONVERGED | CONTINUE]
+```
+
+## Convergence Rules
+- **CONVERGED** if:
+    - No new CRITICAL issues AND
+    - New issue rate < 10% vs previous stage AND
+    - False positive rate < 20%
+- **CONTINUE** if:
+    - New issues found that need addressing and do not meet the above criteria.
+
+## Escalation Rules
+- **ESCALATE_TO_HUMAN** if:
+    - After 5 stages, still finding CRITICAL issues OR
+    - Uncertain about severity or correctness OR
+    - False positive rate > 30%
+
+## Convergence Check Output Format
+```
+New CRITICAL issues: [count]
+Total new issues: [count]
+New issues vs Previous Stage: [percentage change]
+Estimated false positive rate: [percentage]
+Status: [CONVERGED | CONTINUE | NEEDS_ITERATION | ESCALATE_TO_HUMAN]
+```

package/content/distilled/rule-of-5-universal/references/examples.md

@@ -0,0 +1,69 @@
+# Rule of 5 Domain-Specific Examples
+
+## Example 1: Code Review
+
+**Input:**
+```python
+def process_users(users):
+    results = []
+    for user in users:
+        if user.age > 18:
+            results.append(user.name.upper())
+    return results
+```
+
+**Output (abbreviated):**
+
+```
+STAGE 1: DRAFT
+Shape Quality: GOOD - Simple function, clear structure
+
+STAGE 2: CORRECTNESS
+[CORR-001] HIGH - Line 4
+Description: No null check on user.name
+Evidence: Will crash if user.name is None
+Recommendation: Add null check: `if user.name: results.append(user.name.upper())`
+
+STAGE 3: CLARITY
+[CLAR-001] MEDIUM - Function name
+Description: "process_users" is vague
+Recommendation: Rename to "get_adult_user_names_uppercase"
+
+STAGE 4: EDGE CASES
+[EDGE-001] HIGH - Line 2
+Description: Empty users list not handled efficiently
+Recommendation: Add early return: `if not users: return []`
+
+STAGE 5: EXCELLENCE
+Production Ready: WITH_NOTES - Fix CORR-001 and EDGE-001 first
+```
+
+## Example 2: Plan Review
+
+**Input:** Plan for implementing user authentication
+
+**Output (abbreviated):**
+
+```
+STAGE 1: DRAFT
+Shape Quality: FAIR - Missing rollback phase and testing phase
+
+STAGE 2: CORRECTNESS
+[CORR-001] CRITICAL - Phase 3
+Description: Assumes JWT library handles all validation automatically
+Evidence: Most libraries require explicit error handling
+Recommendation: Add error handling to Phase 3, add test for invalid tokens
+
+STAGE 3: CLARITY
+[CLAR-001] HIGH - Phase 2
+Description: "Integrate with auth system" is vague
+Recommendation: Specify files: "Update api/middleware/auth.ts and api/routes/protected.ts"
+
+STAGE 4: EDGE CASES
+[EDGE-001] HIGH - Overall
+Description: No plan for token expiration or refresh
+Recommendation: Add Phase 4 for token refresh mechanism or mark as out of scope
+
+STAGE 5: EXCELLENCE
+Production Ready: NO - Fix CORR-001 and add missing phases
+```

package/content/distilled/rule-of-5-universal/references/templates.md

@@ -0,0 +1,136 @@
+# Rule of 5 Output Templates
+
+Use these templates for each stage of the review and the final report.
+
+## Stage 1: DRAFT
+```
+STAGE 1: DRAFT
+
+Assessment: [1-2 sentences on overall shape]
+
+Major Issues:
+[DRAFT-001] [CRITICAL|HIGH|MEDIUM|LOW] - [Location]
+Description: [What's wrong structurally]
+Recommendation: [How to fix]
+
+[DRAFT-002] ...
+
+Shape Quality: [EXCELLENT|GOOD|FAIR|POOR]
+```
+
+## Stage 2: CORRECTNESS
+```
+STAGE 2: CORRECTNESS
+
+Issues Found:
+[CORR-001] [CRITICAL|HIGH|MEDIUM|LOW] - [Location]
+Description: [What's incorrect]
+Evidence: [Why this is wrong]
+Recommendation: [How to fix with specifics]
+
+[CORR-002] ...
+
+Correctness Quality: [EXCELLENT|GOOD|FAIR|POOR]
+```
+
+## Stage 3: CLARITY
+```
+STAGE 3: CLARITY
+
+Issues Found:
+[CLAR-001] [HIGH|MEDIUM|LOW] - [Location]
+Description: [What's unclear]
+Impact: [Why this matters]
+Recommendation: [How to improve clarity]
+
+[CLAR-002] ...
+
+Clarity Quality: [EXCELLENT|GOOD|FAIR|POOR]
+```
+
+## Stage 4: EDGE CASES
+```
+STAGE 4: EDGE CASES
+
+Issues Found:
+[EDGE-001] [CRITICAL|HIGH|MEDIUM|LOW] - [Location]
+Description: [What edge case is unhandled]
+Scenario: [When this could happen]
+Impact: [What goes wrong]
+Recommendation: [How to handle it]
+
+[EDGE-002] ...
+
+Edge Case Coverage: [EXCELLENT|GOOD|FAIR|POOR]
+```
+
+## Stage 5: EXCELLENCE
+```
+STAGE 5: EXCELLENCE
+
+Final Polish Issues:
+[EXCL-001] [HIGH|MEDIUM|LOW] - [Location]
+Description: [What could be better]
+Recommendation: [How to achieve excellence]
+
+[EXCL-002] ...
+
+Excellence Assessment:
+- Structure: [EXCELLENT|GOOD|FAIR|POOR]
+- Correctness: [EXCELLENT|GOOD|FAIR|POOR]
+- Clarity: [EXCELLENT|GOOD|FAIR|POOR]
+- Edge Cases: [EXCELLENT|GOOD|FAIR|POOR]
+- Overall: [EXCELLENT|GOOD|FAIR|POOR]
+
+Production Ready: [YES|NO|WITH_NOTES]
+```
+
+## Final Report
+```
+# Rule of 5 Review - Final Report
+
+**Work Reviewed:** [type] - [path/identifier]
+**Convergence:** Stage [N]
+
+## Summary
+
+Total Issues by Severity:
+- CRITICAL: [count] - Must fix before proceeding
+- HIGH: [count] - Should fix before proceeding
+- MEDIUM: [count] - Consider addressing
+- LOW: [count] - Nice to have
+
+## Top 3 Critical Findings
+
+1. [ID] [Description] - [Location]
+   Impact: [Why this matters]
+   Fix: [What to do]
+
+2. [ID] [Description] - [Location]
+   Impact: [Why this matters]
+   Fix: [What to do]
+
+3. [ID] [Description] - [Location]
+   Impact: [Why this matters]
+   Fix: [What to do]
+
+## Stage-by-Stage Quality
+
+- Stage 1 (Draft): [Quality assessment]
+- Stage 2 (Correctness): [Quality assessment]
+- Stage 3 (Clarity): [Quality assessment]
+- Stage 4 (Edge Cases): [Quality assessment]
+- Stage 5 (Excellence): [Quality assessment]
+
+## Recommended Actions
+
+1. [Action 1 - specific and actionable]
+2. [Action 2 - specific and actionable]
+3. [Action 3 - specific and actionable]
+
+## Verdict
+
+[READY | NEEDS_REVISION | NEEDS_REWORK | NOT_READY]
+
+**Rationale:** [1-2 sentences explaining the verdict]
+```