incitaciones 0.1.0

package/content/distilled/create-issues/references/templates.md

@@ -0,0 +1,75 @@
+# Issue Creation Templates
+
+Use these templates for proposed slice breakdowns, issue descriptions, and the final creation summary.
+
+## Proposed Slice Review Template
+
+```markdown
+1. **[Title]**
+   - **Type:** [AFK|HITL]
+   - **Blocked by:** [None | Slice 1, Slice 2]
+   - **User stories covered:** [Story A, Story B]
+   - **Tracer-bullet rationale:** [Why this is a thin end-to-end slice]
+```
+
+## Issue Description Template
+
+```markdown
+## Parent
+
+[Reference to parent plan/spec/issue, if applicable]
+
+## What to build
+
+[Describe the end-to-end behavior of this slice in domain language.]
+
+**Context:** [Brief explanation tied to the source plan/spec]
+Ref: [Link to plan/spec file and section]
+
+**Files / Systems:**
+- `path/to/file1`
+- `path/to/file2`
+- `[subsystem or surface area if exact files are not yet known]`
+
+## Acceptance Criteria
+
+- [ ] [Binary, observable criterion 1]
+- [ ] [Binary, observable criterion 2]
+- [ ] [Automated tests cover the slice end-to-end]
+
+## Blocked by
+
+- [Issue reference] 
+
+Or: `None - can start immediately`
+
+---
+**CRITICAL: Follow Test Driven Development and Tidy First workflows.**
+- Write tests *before* writing implementation code.
+- Clean up related code *before* adding new functionality.
+```
+
+## Issue Creation Summary Template
+
+```markdown
+## Issue Creation Summary
+
+**System:** [e.g., GitHub/Beads]
+**Plan:** [path/to/plan.md]
+
+### Approved Slice Set
+1. **[Title]** — [AFK|HITL], blocked by [None|IDs]
+2. **[Title]** — [AFK|HITL], blocked by [None|IDs]
+
+### Summary
+- **Total Issues Created:** [count]
+- **Dependencies Defined:** [count]
+- **Labels Applied:** [e.g., needs-triage]
+
+### Created Issues
+1. **[ID] [Title]** - [Link/Reference]
+2. **[ID] ...**
+
+### Verdict: [ISSUES_CREATED | FAILED_TO_CREATE | WAITING_FOR_APPROVAL]
+**Rationale:** [1-2 sentences explaining the result]
+```

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

@@ -0,0 +1,19 @@
+# Create Implementation Plan
+
+Create a detailed implementation plan for the requested feature.
+
+## Procedure
+
+1. Read any provided spec or task description fully.
+2. Research the codebase and existing patterns.
+3. If multiple approaches are viable, present options and get alignment before finalizing.
+4. Write the plan using `references/plan-template.md`.
+5. If needed, use `references/scenarios.md` for example interaction patterns.
+
+## Rules
+
+- Be specific: include actual file paths and concrete changes.
+- Plan tests before implementation for each phase.
+- Keep phases independently verifiable.
+- Resolve open questions with normal user clarification, not tool-specific assumptions.
+- Prefer realistic plans over exhaustive but unusable plans.

package/content/distilled/create-plan/references/plan-template.md

@@ -0,0 +1,87 @@
+```markdown
+# [Feature Name] Implementation Plan
+
+Date: YYYY-MM-DD
+
+## Overview
+
+[Brief description of what is being implemented]
+
+## Related
+
+- Spec: `specs/...` [if applicable]
+- Research: `research/...` [if applicable]
+- Related issues or tickets: [references]
+
+## Current State
+
+[What exists now and what is missing]
+
+## Desired End State
+
+[What will exist after implementation]
+
+How to verify:
+- [Specific verification step]
+- [Expected behavior]
+
+## Out of Scope
+
+[What is explicitly excluded]
+
+## Risks & Mitigations
+
+[Key risks and mitigations]
+
+## Phase 1: [Name]
+
+### Changes Required
+
+File: `path/to/file.ext`
+- Changes: [Specific modifications needed]
+- Tests: [What to write first]
+
+### Implementation Approach
+
+[How this phase should be implemented]
+
+### Success Criteria
+
+Automated:
+- [ ] Tests pass
+- [ ] Type checking passes [if applicable]
+- [ ] Linting passes [if applicable]
+- [ ] Build succeeds [if applicable]
+
+Manual:
+- [ ] [Manual verification step]
+
+### Dependencies
+
+[Dependencies or blockers]
+
+---
+
+## Testing Strategy
+
+Following TDD:
+1. Write tests first.
+2. Confirm they fail.
+3. Implement the minimum to pass.
+4. Refactor while staying green.
+
+Test types needed:
+- Unit tests: [What to cover]
+- Integration tests: [What to cover]
+- E2E tests: [If applicable]
+
+## Rollback Strategy
+
+[How to back out safely]
+
+## Related Links
+
+- [Documentation]
+- [Similar implementation]
+- [External resource]
+```

package/content/distilled/create-plan/references/scenarios.md

@@ -0,0 +1,19 @@
+## Example Scenarios
+
+### Feature with spec
+
+- Read the spec.
+- Research existing patterns.
+- Propose a phased plan grounded in the codebase.
+
+### No spec, only feature description
+
+- Research the current implementation.
+- Present viable options if there is a meaningful design choice.
+- Recommend one approach and then write the detailed plan.
+
+### Complex feature with technical uncertainty
+
+- Research the architectural constraints first.
+- Present 2-3 options with tradeoffs.
+- Get user alignment before writing the final plan.

package/content/distilled/debug/SKILL.md

@@ -0,0 +1,42 @@
+<!-- skill: debug, version: 1.1.0, status: verified -->
+# Systematic Debugging (Differential Diagnosis)
+
+Apply a clinical, systematic approach to debugging complex software issues using the principles of **Differential Diagnosis (DDx)** to eliminate anchoring bias and find root causes.
+
+## Role
+You are an Expert Systems Diagnostician. Your goal is to move from a symptom to a confirmed root cause through a structured process of elimination, treating the system as a patient with observable "illness scripts."
+
+## Procedure
+
+1.  **Symptom Representation:**
+    *   Describe the primary symptom (e.g., latency spike, intermittent 500s).
+    *   Describe the system context (e.g., Node.js on K8s, PostgreSQL).
+    *   **Re-state the Problem:** Translate the user's description into precise engineering terminology.
+
+2.  **Differential Diagnosis (Hypotheses):**
+    *   List all plausible root causes (Hypotheses), from most likely to least likely.
+    *   Include at least one "Zebra" (a rare, non-obvious cause) to prevent premature closure.
+
+3.  **Illness Scripts:**
+    *   For the top 3 hypotheses, describe the "illness script"—the typical narrative or pattern of how that specific cause would manifest in metrics, logs, or behavior.
+
+4.  **Diagnostic Testing (CRITICAL):**
+    *   For each hypothesis, propose a specific, executable test (command, query, or metric check) to *conclusively rule it out*.
+    *   **Verification Phase:** Use `run_shell_command`, `read_file`, or `grep_search` to actually execute these tests or examine relevant logs/configs if the environment allows. **DO NOT** just simulate results if you have the tools to check reality.
+
+5.  **Evidence Synthesis:**
+    *   If you cannot run tests, simulate the logic: "If Test #1 (most likely) is negative, what does that eliminate? If Test #2 is positive, what does that confirm?"
+    *   State the **Probable Diagnosis** based on the evidence.
+
+6.  **Treatment Recommendation:**
+    *   Propose a specific, immediate action to mitigate the issue.
+    *   Propose a long-term fix to prevent recurrence.
+
+## Rules
+- **No Anchoring:** Do not fixate on the first cause. You must generate at least 4 hypotheses before narrowing.
+- **Evidence-Based:** Every diagnosis must be linked to a specific test result or observation.
+- **Clinical Precision:** Use precise terminology (e.g., "CPU Saturation," "Connection Pool Exhaustion," "B-Tree Index Fragmentation").
+
+## References
+- **Templates:** Use `references/templates.md` for the DDx report structure.
+- **Criteria:** See `references/criteria.md` for severity levels of "illness" and diagnostic confidence rules.

package/content/distilled/debug/references/criteria.md

@@ -0,0 +1,27 @@
+# Systematic Debugging Criteria
+
+Use these criteria to evaluate the quality of a debugging diagnosis.
+
+## Diagnostic Confidence Rules
+
+| Confidence | Criteria | Action |
+| :--- | :--- | :--- |
+| **High** | Hypothesis verified by direct evidence (log trace, metric spike, failing test) and related causes ruled out. | **Implement fix.** |
+| **Medium** | Hypothesis consistent with symptoms and simulated tests positive, but direct evidence missing. | **Gather more logs.** |
+| **Low** | Hypothesis only explains some symptoms; major contradictions remain. | **Re-run DDx.** |
+
+## "Illness Severity" (Bug Prioritization)
+
+| Severity | Criteria | Treatment Strategy |
+| :--- | :--- | :--- |
+| **CRITICAL** | Production data loss, security breach, or system-wide outage. | **Immediate mitigation first (Restart/Rollback), then root cause fix.** |
+| **HIGH** | Severe performance degradation or core feature broken. | **Prioritize fix above all in-flight work.** |
+| **MEDIUM** | Intermittent error or minor feature failure. | **Add monitoring/logging to catch next occurrence.** |
+| **LOW** | Cosmetic or non-functional issue. | **Record in backlog for future fix.** |
+
+## Hypotheses Quality Checklist
+
+- [ ] **Broad Spectrum:** Did you list at least 4 hypotheses?
+- [ ] **Zebra Presence:** Did you include at least one non-obvious cause?
+- [ ] **Mutual Exclusivity:** Are the hypotheses distinct, or are they different symptoms of the same cause?
+- [ ] **Executable Verification:** Is there at least one test for each that uses a project tool or command?

package/content/distilled/debug/references/templates.md

@@ -0,0 +1,39 @@
+# Systematic Debugging Templates
+
+Use this template for reporting findings during a Differential Diagnosis (DDx) session.
+
+## Differential Diagnosis Report
+
+```markdown
+### 1. Problem Representation
+**Symptom:** [User's description]
+**System:** [Brief context]
+**Refined Representation:** [Engineering terminology for the problem]
+
+### 2. Hypotheses (Differential Diagnosis)
+1.  **[Hypothesis 1]** (Probability: High) - [Brief reasoning]
+2.  **[Hypothesis 2]** (Probability: Medium) - [Brief reasoning]
+3.  **[Hypothesis 3]** (Probability: Medium) - [Brief reasoning]
+4.  **[Hypothesis 4]** (Probability: Low) - [Brief reasoning]
+5.  **[Hypothesis 5 (ZEBRA)]** (Probability: Very Low) - [Brief reasoning]
+
+### 3. Top 3 Illness Scripts
+1.  **[Hypothesis 1]:** [How it manifests in metrics/logs]
+2.  **[Hypothesis 2]:** [How it manifests in metrics/logs]
+3.  **[Hypothesis 3]:** [How it manifests in metrics/logs]
+
+### 4. Diagnostic Tests & Verified Results
+| Hypothesis | Diagnostic Test | Result (Verified/Simulated) | Finding |
+| :--- | :--- | :--- | :--- |
+| **H1** | [Executable test] | [Positive/Negative] | [What was found] |
+| **H2** | [Executable test] | [Positive/Negative] | [What was found] |
+| **H3** | [Executable test] | [Positive/Negative] | [What was found] |
+
+### 5. Probable Diagnosis
+**Conclusion:** [State the most likely root cause based on findings]
+**Confidence Score:** [0-100%]
+
+### 6. Treatment Plan
+**Immediate Mitigation:** [Specific action to restore service]
+**Long-term Fix:** [Specific action to prevent recurrence]
+```

package/content/distilled/describe-pr/SKILL.md

@@ -0,0 +1,17 @@
+# Generate PR Description
+
+Create a pull request description based on the actual PR changes.
+
+## Procedure
+
+1. Identify the PR.
+2. Gather diff, commit history, and metadata.
+3. Analyze what changed, why it changed, and reviewer-relevant impact.
+4. Generate the description using `references/pr-template.md`.
+5. Show the draft to the user before updating the PR.
+
+## Rules
+
+- Focus on why, not just what.
+- Be specific about impact, testing, and reviewer guidance.
+- Highlight breaking changes, security implications, and rollout concerns when present.

package/content/distilled/describe-pr/references/pr-template.md

@@ -0,0 +1,62 @@
+```markdown
+## Summary
+
+[2-3 sentence overview of what the PR does and why]
+
+## Changes
+
+Key changes:
+- [Specific change with rationale]
+- [Specific change with rationale]
+
+Files changed:
+- `path/to/file.ext` - [What changed and why]
+
+## Motivation
+
+[Problem solved or requirement fulfilled]
+
+## Implementation Details
+
+[Key decisions and tradeoffs]
+
+## Related
+
+- Issue: [reference if applicable]
+- Plan: `plans/...` [if applicable]
+- Design doc: `docs/...` [if applicable]
+- Depends on: [PR or issue]
+- Blocks: [PR or issue]
+
+## Testing
+
+Automated:
+- [ ] [Command or suite]
+
+Manual:
+- [ ] [Verification step]
+
+## Breaking Changes
+
+[List them, or state none]
+
+## Security Considerations
+
+[List them, or state none]
+
+## Performance Impact
+
+[List them, or state none]
+
+## Rollout Plan
+
+[If needed]
+
+## Follow-up Work
+
+- [ ] [Follow-up]
+
+## Reviewer Notes
+
+[What reviewers should focus on]
+```

package/content/distilled/design-practice.md

@@ -0,0 +1,213 @@
+Apply the 6-phase design framework to understand a problem before implementing a solution.
+
+## Phases
+
+Work through each phase sequentially. Do not skip phases. The goal is understanding, not artifacts.
+
+### PHASE 1: DESCRIBE (Symptoms)
+
+**Objective:** Capture the reality without imposing solutions.
+
+1. **Gather signals:**
+   - What symptoms are observed? (errors, complaints, metrics)
+   - Where do they occur? (files, components, conditions)
+   - When did they start? (commits, deployments, changes)
+   - Who is affected? (users, systems, processes)
+
+2. **Write a neutral description:**
+   - Facts only, no speculation on causes
+   - No mention of solutions
+   - Observable behaviors, not interpretations
+
+**Output format:**
+```
+## Description
+
+### Observed Symptoms
+- [Symptom 1]: [Where/When observed]
+- [Symptom 2]: [Where/When observed]
+
+### Signal Sources
+- [Bug reports, logs, user complaints, metrics]
+
+### Timeline
+- [When symptoms first appeared, any patterns]
+```
+
+**Anti-patterns to avoid:**
+- "The database is slow" (diagnosis, not description)
+- "We need to add caching" (solution, not description)
+- "Users are confused by the UI" (interpretation, not observation)
+
+**Correct examples:**
+- "Page load time exceeds 5s when user count > 100"
+- "Error rate increased from 0.1% to 2.3% after deploy on Jan 15"
+- "Users submit support tickets asking how to find the export button"
+
+### PHASE 2: DIAGNOSE (Root Cause)
+
+**Objective:** Identify the mechanism causing the symptoms.
+
+1. **Generate multiple hypotheses:**
+   - List at least 3 possible causes
+   - "If I only have one hypothesis, I'm probably wrong"
+
+2. **Test hypotheses systematically:**
+   - Use logic to rule things out (negative progress)
+   - Use evidence to support remaining hypotheses
+   - Divide and conquer (git bisect, component isolation)
+
+3. **Write the Problem Statement:**
+
+**Problem Statement Template:**
+```
+## Problem Statement
+
+**Current behavior:** [What happens now - factual]
+
+**Mechanism:** [Root cause - how/why it happens]
+
+**Evidence:**
+- [Fact supporting this diagnosis]
+- [Fact supporting this diagnosis]
+
+**Ruled out:**
+- [Hypothesis A]: [Why it's not this]
+- [Hypothesis B]: [Why it's not this]
+```
+
+**Quality check:** The solution should feel obvious after writing the right problem statement. If it doesn't, the diagnosis is incomplete.
+
+### PHASE 3: DELIMIT (Scope)
+
+**Objective:** Define what's in and what's out.
+
+1. **Set explicit boundaries:**
+   - What subset of the problem will we solve?
+   - What constraints do we accept?
+   - What's explicitly NOT being addressed?
+
+2. **Document non-goals:**
+   - Future considerations
+   - Related problems not in scope
+   - Nice-to-haves deferred
+
+**Output format:**
+```
+## Scope
+
+### In Scope
+- [What we will address]
+- [Specific constraints we'll work within]
+
+### Out of Scope (Non-Goals)
+- [What we explicitly won't do]
+- [Why it's deferred]
+
+### Constraints
+- [Technical limitations]
+- [Time/resource constraints]
+- [Compatibility requirements]
+```
+
+**Why this matters:** Prevents scope creep. Sets the "physics" of the project before considering solutions.
+
+### PHASE 4: DIRECTION (Strategic Approach)
+
+**Objective:** Select the best approach from viable alternatives.
+
+1. **Generate multiple approaches:**
+   - **Status Quo**: Always include "do nothing" as baseline
+   - **Approach A**: [First viable approach]
+   - **Approach B**: [Different viable approach]
+   - **Approach C**: [If applicable]
+
+2. **Build a Decision Matrix:**
+
+**Decision Matrix Structure:**
+```
+## Decision Matrix
+
+| Criterion | Status Quo | Approach A | Approach B |
+|-----------|------------|------------|------------|
+| [Criterion 1] | [Fact] | [Fact] | [Fact] |
+| [Criterion 2] | [Fact] | [Fact] | [Fact] |
+| [Criterion 3] | [Fact] | [Fact] | [Fact] |
+
+### Criteria Definitions
+- **[Criterion 1]**: [What this measures]
+- **[Criterion 2]**: [What this measures]
+
+### Assessment Key
+- Green: Desirable
+- Yellow: Acceptable with trade-offs
+- Red: Problematic or blocking
+```
+
+**Rules for Decision Matrix:**
+- Text is FACT (neutral, objective descriptions)
+- Color/assessment is JUDGMENT (subjective evaluation)
+- Status Quo is always the first column
+- Each cell must be specific, not "good" or "bad"
+
+3. **Select and justify:**
+```
+### Decision
+
+**Selected approach:** [Approach name]
+
+**Rationale:** [Why this approach best addresses the scoped problem]
+
+**Trade-offs accepted:** [What we're giving up]
+```
+
+### PHASE 5: DESIGN (Tactical Plan)
+
+**Objective:** Create detailed blueprint for implementation.
+
+Only after Direction is selected:
+
+1. **Define specifics:**
+   - Data structures and schemas
+   - API signatures and contracts
+   - Component responsibilities
+   - Error handling approach
+   - Edge cases
+
+2. **Write Implementation Plan:**
+
+Use the standard implementation plan format with:
+- Phases that can be independently verified
+- TDD approach (tests before implementation)
+- Specific file paths and changes
+- Success criteria for each phase
+
+**Hammock time:** Write the plan, then sleep on it. Read it the next day before proceeding.
+
+### PHASE 6: DEVELOP (Execute)
+
+**Objective:** Translate design into working code.
+
+If Phases 1-5 were rigorous, this phase should feel mechanical:
+- Follow the plan
+- Write tests first
+- Implement to pass tests
+- Verify against success criteria
+
+**If you're struggling in this phase:** Return to earlier phases. Struggling to code usually means the design is incomplete.
+
+## Process Rules
+
+1. **No phase skipping:** Each phase builds on the previous
+2. **Artifacts are thinking tools:** Not bureaucracy, but aids to understanding
+3. **Hammock time:** Sleep on ideas before committing to them
+4. **Multiple hypotheses:** One idea is a trap; generate alternatives
+5. **Incremental over iterative:** Understand → Design → Code → Value (not Code → Fail → Learn)
+
+## When to Return to Earlier Phases
+
+- **Can't write Problem Statement clearly** → Back to Describe (need more symptoms)
+- **Solution doesn't feel obvious** → Back to Diagnose (incomplete root cause)
+- **Scope keeps expanding** → Back to Delimit (boundaries not firm)
+- **Can't choose between approaches** → Back to Direction (need more criteria or research)
+- **Implementation keeps hitting surprises** → Back to Design (missing edge cases)

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

@@ -0,0 +1,29 @@
+# Design Artifact Review
+
+Review design artifacts for rigor, completeness, and adherence to Design in Practice principles.
+
+## Setup
+
+- If an artifact path is provided, read it completely.
+- If no path is provided, ask which artifact to review or list available design documents.
+
+## Procedure
+
+1. Identify the artifact type:
+   - Problem statement
+   - Decision matrix
+   - Scope document
+   - Full design package
+2. Run the appropriate review:
+   - For problem statements, use `references/problem-statement.md`.
+   - For decision matrices, use `references/decision-matrix.md`.
+   - For scope documents, use `references/scope-document.md`.
+   - For full design packages, use `references/combined-review.md`.
+3. Generate the final output using `references/report-template.md`.
+
+## Rules
+
+- Reference exact evidence from the artifact.
+- Use the artifact-specific output format from the reference file.
+- Prefer the most critical issue over exhaustive nitpicks.
+- If multiple artifacts are supplied, review each individually before synthesizing.

package/content/distilled/design-review/references/combined-review.md

@@ -0,0 +1,27 @@
+## Full Design Package Review
+
+Use this when reviewing multiple related artifacts together.
+
+### Alignment Check
+
+Validate:
+- The problem statement describes the actual problem without embedding the solution.
+- The decision matrix evaluates approaches that actually address that problem.
+- The scope document or plan respects the chosen approach and non-goals.
+
+Output:
+
+```text
+## Alignment Review
+
+Problem -> Options alignment:
+- [Evidence of alignment or drift]
+
+Decision -> Scope alignment:
+- [Evidence of scope adherence or creep]
+
+Decision -> Plan execution:
+- [Does the plan execute on the decision rationale?]
+```
+
+Use the artifact-specific references first, then append this alignment section before the final report.