incitaciones 0.1.0

package/pi-package/skills/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/pi-package/skills/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/pi-package/skills/describe-pr/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: describe-pr
+description: "Generate clear PR descriptions from code changes"
+metadata:
+  installed-from: "incitaciones"
+---
+# 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/pi-package/skills/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/pi-package/skills/design-practice/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: design-practice
+description: "Rich Hickey-inspired design methodology workflow"
+metadata:
+  installed-from: "incitaciones"
+---
+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/pi-package/skills/design-review/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: design-review
+description: "Review problem statements and decision matrices"
+metadata:
+  installed-from: "incitaciones"
+---
+# 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/pi-package/skills/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.

package/pi-package/skills/design-review/references/decision-matrix.md

@@ -0,0 +1,122 @@
+## Decision Matrix Review
+
+### Check 1: Status Quo Baseline
+
+Question: Is "do nothing" the first column?
+
+Output:
+
+```text
+Status Quo Baseline: [PRESENT | MISSING]
+
+If missing:
+- Impact: Cannot compare alternatives to current state
+- Fix: Add Status Quo column with honest assessment
+```
+
+### Check 2: Fact vs. Judgment Separation
+
+Question: Is cell text factual and neutral, with judgment shown separately?
+
+Contaminated cells:
+- "Good performance"
+- "Easy to implement"
+- "Better than X"
+
+Clean cells:
+- "< 10ms p99 latency"
+- "Requires changes to 3 files"
+- "Uses existing auth pattern"
+
+Output:
+
+```text
+Fact/Judgment Separation: [CLEAN | CONTAMINATED]
+
+Contaminated cells:
+| Row | Column | Current Text | Factual Rewrite |
+|-----|--------|--------------|-----------------|
+| [Row] | [Col] | "[Text]" | "[Suggestion]" |
+
+Assessment indicators:
+- Are judgments shown via color or symbol, not text? [YES/NO]
+```
+
+### Check 3: Criteria Completeness
+
+Question: Are all relevant trade-off dimensions represented?
+
+Common missing criteria:
+- Maintenance burden
+- Rollback difficulty
+- Team expertise
+- Integration complexity
+- Failure modes
+
+Output:
+
+```text
+Criteria Completeness: [COMPLETE | GAPS]
+
+Present criteria: [List]
+
+Potentially missing:
+- [Criterion]: [Why it matters]
+- [Criterion]: [Why it matters]
+
+Recommendation:
+- [Which criteria to add]
+```
+
+### Check 4: Approach Diversity
+
+Question: Are the approaches fundamentally different, or variations of the same idea?
+
+Output:
+
+```text
+Approach Diversity: [DIVERSE | SIMILAR]
+
+Approaches listed:
+- [Approach 1]: [Category]
+- [Approach 2]: [Category]
+- [Approach 3]: [Category]
+
+Missing perspectives:
+- [What category of solution was not considered]
+```
+
+### Check 5: Cell Verification
+
+Question: Are the facts in the matrix verifiable and accurate?
+
+Output:
+
+```text
+Cell Verification: [VERIFIED | MIXED | UNVERIFIED]
+
+Verified cells:
+- [Cell Row/Col]: [Claim] -> [Verification result]
+
+Incorrect or unsupported cells:
+- [Cell]: [What's wrong and what's correct]
+```
+
+### Verdict Template
+
+```text
+## Decision Matrix Review Summary
+
+| Check | Result | Action Needed |
+|-------|--------|---------------|
+| Status Quo | [PRESENT/MISSING] | [Action or "None"] |
+| Fact/Judgment | [CLEAN/CONTAMINATED] | [Action or "None"] |
+| Criteria | [COMPLETE/GAPS] | [Action or "None"] |
+| Diversity | [DIVERSE/SIMILAR] | [Action or "None"] |
+| Verification | [VERIFIED/MIXED/UNVERIFIED] | [Action or "None"] |
+
+Verdict: [READY_FOR_DECISION | NEEDS_REVISION | NEEDS_MORE_OPTIONS]
+Selected approach justified? [YES/NO]
+Top Issue: [Most critical thing to fix]
+Recommended Action: [Specific next step]
+```

package/pi-package/skills/design-review/references/problem-statement.md

@@ -0,0 +1,141 @@
+## Problem Statement Review
+
+### Check 1: Solution Contamination
+
+Question: Does the problem statement contain or imply solutions?
+
+Red flags:
+- "We need to..."
+- Technology names unless they are the problem
+- "Add", "implement", "create", "build"
+- Comparisons to how other systems work
+
+Test:
+- YES: multiple fundamentally different solutions fit the statement -> clean
+- NO: the solution is embedded -> contaminated
+
+Output:
+
+```text
+Solution Contamination: [CLEAN | CONTAMINATED]
+
+Evidence:
+- [Quote from statement showing contamination, or "None found"]
+
+Recommendation:
+- [How to remove solution language]
+```
+
+### Check 2: Root Cause vs. Symptom
+
+Question: Does this describe the mechanism, or just the observable effect?
+
+Symptom language:
+- "Users experience..."
+- "The system is slow/broken/failing..."
+- "Errors occur when..."
+
+Mechanism language:
+- "Because X happens, Y results in Z"
+- "The [component] does [action] which causes [effect]"
+- Clear causal chain
+
+Test: Ask "Why?" If there is a deeper answer, this is still a symptom.
+
+Output:
+
+```text
+Root Cause Analysis: [MECHANISM | SYMPTOM | UNCLEAR]
+
+Depth check:
+- Statement says: [quote]
+- Ask "Why?": [deeper cause if exists]
+- Assessment: [Is this the root or just a layer?]
+
+Recommendation:
+- [How to dig deeper, or "Root cause identified"]
+```
+
+### Check 3: Specificity
+
+Question: Is the problem precise enough to guide solution selection?
+
+Vague indicators:
+- "Performance issues"
+- "Users are confused"
+- "The code is messy"
+
+Specific indicators:
+- Quantified thresholds
+- Named components
+- Reproducible conditions
+
+Output:
+
+```text
+Specificity: [PRECISE | VAGUE | MIXED]
+
+Vague elements:
+- [Element 1]: [How to make specific]
+- [Element 2]: [How to make specific]
+
+Missing specifics:
+- [What metric, threshold, or condition is unclear]
+```
+
+### Check 4: Evidence Quality
+
+Question: Is the diagnosis based on verified facts or assumptions?
+
+Look for:
+- Evidence cited for each claim
+- Ruled-out alternatives
+- Hypothesis testing
+- Data sources
+
+Output:
+
+```text
+Evidence Quality: [VERIFIED | ASSUMED | MIXED]
+
+Claims without evidence:
+- [Claim 1]: [What evidence is needed]
+- [Claim 2]: [What evidence is needed]
+
+Ruled-out alternatives:
+- [Listed? How many? Are they reasonable alternatives?]
+```
+
+### Check 5: The Obvious Solution Test
+
+Question: Does the solution feel obvious after reading this statement?
+
+Output:
+
+```text
+Obvious Solution Test: [PASS | FAIL | PARTIAL]
+
+After reading, the obvious action is: [What seems like the right solution]
+
+If FAIL:
+- What's unclear: [What question remains]
+- What's missing: [What would make it obvious]
+```
+
+### Verdict Template
+
+```text
+## Problem Statement Review Summary
+
+| Check | Result | Action Needed |
+|-------|--------|---------------|
+| Solution Contamination | [CLEAN/CONTAMINATED] | [Action or "None"] |
+| Root Cause | [MECHANISM/SYMPTOM] | [Action or "None"] |
+| Specificity | [PRECISE/VAGUE] | [Action or "None"] |
+| Evidence | [VERIFIED/ASSUMED] | [Action or "None"] |
+| Obvious Solution | [PASS/FAIL] | [Action or "None"] |
+
+Verdict: [READY_FOR_DIRECTION | NEEDS_REVISION | BACK_TO_DESCRIBE]
+Top Issue: [Most critical thing to fix]
+Recommended Action: [Specific next step]
+```