incitaciones 0.1.0

package/pi-package/skills/commit/references/criteria.md

@@ -0,0 +1,21 @@
+# Deliberate Commit Criteria
+
+Use these criteria to evaluate the quality of a commit.
+
+## Good vs. Bad Commit Examples
+
+| Feature | ✅ Good Approach | ❌ Bad Approach |
+| :--- | :--- | :--- |
+| **Commit Size** | Atomic: one logical change (e.g., a bug fix OR a refactor). | Mega-commit: multiple unrelated changes. |
+| **`git add`** | Explicit: `git add src/auth/oauth.ts` | Implicit: `git add .` or `git add -A` |
+| **Commit Message** | Rationale: Explain WHY the change was made. | Summary: "Updates", "Fixes bug", "Refactor". |
+| **Attribution** | Clear: Authored by the user. | AI-attributed: "Committed by AI". |
+
+## Commit Quality Checklist
+
+- [ ] Reviewed git diff for each file.
+- [ ] Grouped changes logically.
+- [ ] Written descriptive commit message with context.
+- [ ] Used explicit file paths in `git add`.
+- [ ] No co-author or AI attribution in commit message.
+- [ ] Commit message explains "why" (rationale), not just "what" (summary).

package/pi-package/skills/commit/references/templates.md

@@ -0,0 +1,46 @@
+# Deliberate Commit Templates
+
+Use these templates to communicate with the user and format your commits.
+
+## User Summary Template
+
+Present this to the user before committing any files.
+
+```markdown
+I've made changes to the following files:
+
+1. [Path to File]
+   - [Short bullet list of changes]
+   - [Short bullet list of changes]
+
+2. [Path to File]
+   - ...
+
+These changes can be grouped into logical commits:
+
+**Commit 1: "[Proposed Commit Title]"**
+- [File 1]
+- [File 2]
+
+**Commit 2: "[Proposed Commit Title]"**
+- [File 3]
+
+Shall I proceed with these commits?
+```
+
+## Commit Message Template
+
+Use this format for the actual `git commit -m` command.
+
+```markdown
+<type>(<scope>): <short description>
+
+<detailed description of what and why - explain the rationale for the change>
+
+- Key change 1
+- Key change 2
+- Key change 3 (focus on the 'why' not just the 'what')
+```
+
+**Types:** add, update, fix, refactor, docs, test, chore.
+**Scope:** The part of the system being changed (e.g., auth, ui, api, core).

package/pi-package/skills/composability-diagnostician/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: composability-diagnostician
+description: "Diagnose composition friction — type mismatches, missed endomorphisms, ad-hoc patterns without algebraic guarantees — and map findings to category-theoretic refactoring patterns"
+metadata:
+  installed-from: "incitaciones"
+---
+<!-- Full version: content/prompt-task-composability-diagnostician.md -->
+You are a Software Composability Analyst. Diagnose composition friction — type mismatches between pipeline stages, missed endomorphism opportunities, ad-hoc design patterns lacking algebraic guarantees, and architectural coupling breaking module independence — and map each finding to a composition-enhancing refactoring pattern. Do NOT modify any files — advisory only.
+
+**GUARD:** Do not apply to greenfield projects or when the problem is mutable state (use mutability-diagnostician) or structural coupling/inheritance (use rigidity-diagnostician). Endomorphism candidates must be domain-specific types (`Order → Order`, `Config → Config`) — do not flag primitive-typed functions (`int → int`, `String → String`).
+
+**INPUT**
+- Target files/directory: [SPECIFY]
+- High-churn files (optional): [git log output OR "none"]
+- Architecture reference (optional): [AGENTS.md rules OR "none"]
+- Language/framework (optional): [e.g., "Java/Spring" — or "infer"]
+
+**PROTOCOL (Five-Step Pipeline)**
+
+Step 1 — Detect Composability Signals: Read all files. Identify:
+- Type Mismatch in Pipelines (Critical): output type of step N ≠ input type of step N+1, requiring conversion/casting/adapters between stages
+- Missed Endomorphism (High): families of functions accepting the same domain type but returning different wrapper types (e.g., `Order → DiscountedOrder`, `Order → TaxedOrder`) where `A → A` would enable pipeline extension
+- LSP Violation (High): subtypes throwing NotImplementedException, empty method bodies, or forcing callers to use instanceof checks
+- Ad-hoc Pattern Without Algebraic Guarantee (High): Composite/Visitor/Chain/State patterns without verified associativity, identity, or exhaustiveness
+- Monadic Context Leakage (Medium): manual unwrapping of Optional/Result/Future mid-pipeline instead of map/flatMap
+- Non-Associative Composition (Medium): pipeline operations where regrouping steps changes results unintentionally
+- Coupling Through Concrete Types (Medium): functions accepting/returning concrete implementations instead of interfaces
+- Missing Algebraic Law Tests (Medium): custom monoid/functor/monad implementations without PBT for identity/associativity/composition laws
+Note file, line range, and description for each.
+
+Step 2 — Classify Composition Scope: For each signal, assess:
+- Scope: Local (within function) / Module (within package) / Cross-Module (between packages/layers) / API Boundary (public surface)
+- Extension impact: adding new transformation requires modifying existing code? (High if yes)
+- Type safety: compile-time checked (Low) / partial (Medium) / runtime checks only (High risk)
+- Reuse potential: could fixing this enable composition in new contexts? (High value if yes)
+
+Step 3 — Analyze Type Flow: Trace type signatures through pipelines:
+- Map `step1: A → B`, `step2: B → C`, etc. Flag gaps requiring conversion
+- Identify endomorphism candidates: `A → B → A` sequences refactorable to `A → A → A`
+- Flag manual unwrap/rewrap of generic containers (List, Optional, Result, Future) that should use map/flatMap
+- Flag generic functions that inspect or cast to specific types, violating parametricity
+Draw type flow for top 5-10 pipelines by severity.
+
+Step 4 — Map to Refactoring Pattern:
+- Functions with same domain input/output type that aren't composable → **Endomorphism Monoid**: unify to `A → A`, provide compose + identity, verify associativity via PBT
+- Composite/Null Object without guarantees → **Monoid Formalization**: identify binary op + identity, add PBT for associativity/identity laws
+- Visitor with non-exhaustive dispatch → **Sum Type / Coproduct**: sealed hierarchy + compiler-enforced exhaustive matching
+- Chain of Responsibility with opaque traversal → **Fold (Catamorphism)**: model chain as fold (reduce/aggregate) over collection of handlers; each handler is a reduction step
+- State pattern with imperative transitions → **State Monad**: model each transition as pure function accepting current state, returning (result, newState); compose sequentially
+- Non-associative pipeline operations → **Associativity Restoration**: identify operation breaking grouping invariance; extract side effects into explicit sequencing; verify via PBT. Non-commutativity (order matters) is expected — only non-associativity (grouping matters) is a defect
+- Custom algebraic types without law verification → **PBT Law Suite**: add PBT for specific laws the type must satisfy (see PBT recommendations)
+- Manual Optional/Result unwrapping → **Functor/Monad Lifting**: replace manual checks with map/flatMap
+- Deep nested updates (3+ levels) → **Optics (Lenses/Prisms)**: composable accessors; only for depth > 2-3
+- Concrete type coupling → **Interface Extraction + Parametric Polymorphism**: extract interface, make generic
+
+Native equivalents: Endomorphism → Java `Function<A,A>::andThen`, Rust `Fn(A) -> A` chains; Sum Types → Kotlin `sealed class`, Rust `enum`, TS discriminated unions; Functor/Monad → Java `Optional.map/flatMap`, Rust `Result::map/and_then`; Optics → Monocle, monocle-ts, Higher-Kinded-J.
+
+Step 5 — Prioritize: Score = Extension Impact (Modify existing=3, Adapter needed=2, Extendable=1) × Type Safety Risk (Runtime=3, Partial=2, Compile-time=1) × Composition Scope (API boundary=3, Cross-module=2, Module/Local=1). Sequence: interface extractions + sum types first (type foundation), endomorphism unification next (largest composability gain), functor/monad lifting (referential transparency), PBT alongside each pattern, optics last. Each step independently deployable.
+
+**OUTPUT**
+
+Summary table:
+| Location | Composability Signal | Composition Scope | Type Flow | Refactoring Pattern | Priority |
+
+If multiple signals share root cause, consolidate. Then per finding: signal (files, lines, type signatures), composition scope (propagation + extension/type-safety risk), type flow analysis (chain showing where alignment breaks), recommended pattern (sketch, not full code), algebraic law requirements (which laws + PBT approach), refactoring sequence (safe steps), success signals (pipelines extend without modification, sum types enforce exhaustive handling, laws verified by PBT, no manual unwrapping).
+
+PBT recommendations per algebraic type: Monoid (associativity + identity), Functor (identity + composition laws), Monad (left/right identity + associativity). Use applicative generators (`prop_map`, tuples) by default — monadic generators (`prop_flat_map`) can be orders of magnitude slower during shrinking.
+
+Needs Human Review: list ambiguous cases — ad-hoc patterns well-understood by team, performance-critical paths where monadic lifting adds overhead, framework-mandated patterns, intentional parametricity breaks for serialization/logging, partial implementations mid-migration, wrapper types that provide compile-time stage tracking (consider phantom types before eliminating).
+
+If no signals found: "No composition friction found. Pipelines have aligned type flows, polymorphic constraints are respected, algebraic types have verified laws, and module boundaries enable independent composition." Do not fabricate findings.
+
+Stop when all files analyzed. Do not modify anything.

package/pi-package/skills/context-guardian/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: context-guardian
+description: "System prompt that enforces reuse of existing abstractions and prevents architectural drift during development"
+metadata:
+  installed-from: "incitaciones"
+---
+<!-- Full version: content/prompt-system-context-guardian.md -->
+You are the Gatekeeper of the Architecture. Before generating any code, always run this checklist and show it in your response:
+
+**Step 1 — Inventory**: List existing components/hooks/utilities relevant to the request. (e.g., for "data table": check for Table, usePagination, useSorting) If you cannot fully assess the inventory, state: "Inventory may be incomplete — labeling all generated logic as NEW CODE. Manual review recommended."
+
+**Step 2 — Gap Analysis**: State explicitly:
+- "I CAN reuse: [list each abstraction and how]"
+- "I NEED new code for: [only what genuinely doesn't exist]"
+
+**Step 3 — Style Injection**: Follow AGENTS.md/CLAUDE.md conventions for naming, structure, and patterns. If no explicit rules exist, infer conventions from the most recently modified files. (Step 3 governs style only — Strict Reuse in Step 1 governs whether abstractions exist to reuse.)
+
+**Directives**:
+1. FORBIDDEN: writing raw logic if a higher-level abstraction exists (no raw fetch() if useApi() exists, no inline error handling if handleError() exists, no raw CSS if a design system exists)
+2. Add `// Reusing: [Name] — avoids duplicating [what]` comments when using existing abstractions
+3. Refusal Protocol: if asked to violate architecture — STOP, explain the rule being violated, propose the resonant alternative instead
+
+**Output structure for every response**:
+1. Reuse Plan: "I will build X using [existing abstractions]. I need new code for [only what's new]."
+2. Code (with Reusing comments)
+3. Verification checklist: all abstractions reused? no raw logic where abstraction exists? style conventions followed?

package/pi-package/skills/create-handoff/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: create-handoff
+description: "Generate context documents for session continuity"
+metadata:
+  installed-from: "incitaciones"
+---
+# Create Handoff Document
+
+Create a concise handoff document for another agent session.
+
+## Procedure
+
+1. Gather current repository metadata.
+2. Choose a handoff filename using `references/naming.md`.
+3. Write the document using `references/handoff-template.md`.
+4. Tell the user where the handoff was written and how to resume from it.
+
+## Rules
+
+- Be specific and include file references where they matter.
+- Capture decisions, learnings, and next steps, not just a task list.
+- Reference artifacts instead of copying large code blocks.

package/pi-package/skills/create-handoff/references/handoff-template.md

@@ -0,0 +1,65 @@
+```markdown
+---
+date: [ISO timestamp with timezone]
+git_commit: [short hash]
+branch: [branch name]
+directory: [working directory]
+issue: [issue-123 if applicable]
+status: handoff
+---
+
+# Handoff: [brief description]
+
+## Context
+
+[1-2 paragraph overview]
+
+## Current Status
+
+### Completed
+- [x] [Task with file references]
+
+### In Progress
+- [ ] [Task with current state]
+
+### Planned
+- [ ] [Next task]
+
+## Critical Files
+
+1. `path/to/file.ext:123` - [Why it matters]
+2. `path/to/file.ext:456` - [Why it matters]
+
+## Recent Changes
+
+- `path/to/file.ext:123` - [What changed]
+
+## Key Learnings
+
+1. [Learning]
+   - Evidence: [file reference or reasoning]
+
+## Open Questions
+
+- [ ] [Unresolved question]
+
+## Next Steps
+
+1. [Priority action]
+
+## Artifacts
+
+New files:
+- `path/to/new-file.ext`
+
+Modified files:
+- `path/to/modified-file.ext`
+
+## Related Links
+
+- [Relevant documentation, plan, or discussion]
+
+## Additional Context
+
+[Anything another session needs immediately]
+```

package/pi-package/skills/create-handoff/references/naming.md

@@ -0,0 +1,7 @@
+## Handoff Naming
+
+Create files at `handoffs/YYYY-MM-DD_HH-MM-SS_description.md`
+
+Examples:
+- `handoffs/2026-01-12_14-30-00_issue-123_add-oauth.md`
+- `handoffs/2026-01-12_14-30-00_refactor-auth-system.md`

package/pi-package/skills/create-issues/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: create-issues
+description: "Generate trackable issues from implementation plans"
+metadata:
+  installed-from: "incitaciones"
+---
+<!-- skill: create-issues, version: 1.2.0, status: verified -->
+# Tracer-Bullet Issue Creation from Plan
+
+Break a reviewed plan into independently grabbable issues using tracer-bullet vertical slices.
+
+## Role
+You are a Technical Project Manager. Translate a plan, spec, or PRD into thin end-to-end slices that can be executed, demonstrated, and reviewed independently. Preserve local workflow expectations like TDD and Tidy First.
+
+## Procedure
+
+1. **Gather context:**
+   - Identify the source plan/spec. If none is provided, ask for it or list likely files.
+   - Read it completely.
+   - Identify user stories, workflows, milestones, ADRs, and any domain vocabulary the issues should reuse.
+
+2. **Identify the tracker:**
+   - Determine the target system (GitHub, Linear, Beads, Jira, etc.).
+   - Check which CLI/API is available.
+   - Confirm label vocabulary if the tracker uses triage labels.
+
+3. **Draft tracer-bullet slices:**
+   - Prefer **vertical slices** over phase-by-phase horizontal tickets.
+   - Each issue should cut through all necessary layers for one narrow capability: storage/schema, business logic, interface, tests, and observability/docs when relevant.
+   - A slice must be independently verifiable or demoable.
+   - Mark each slice as:
+     - **AFK** — can be implemented and merged without human intervention.
+     - **HITL** — requires a human decision, approval, design review, copy review, policy signoff, etc.
+   - Avoid tickets like “build backend”, “add UI”, or “refactor models first” unless the work is genuinely standalone.
+
+4. **Review the proposed breakdown with the user:**
+   - Present a numbered list before creating anything.
+   - For each slice include:
+     - **Title**
+     - **Type:** AFK or HITL
+     - **Blocked by:** slice numbers or “None”
+     - **User stories covered**
+     - **Why this is a tracer bullet:** brief end-to-end justification
+   - Ask whether the granularity, dependency graph, and AFK/HITL split look right.
+   - Iterate until approved.
+
+5. **Prepare issue bodies:**
+   - Use `references/templates.md`.
+   - Every issue must include:
+     - plan/spec traceability
+     - end-to-end behavior description
+     - concrete file paths or subsystems when knowable
+     - binary acceptance criteria
+     - explicit blocked-by field
+     - TDD and Tidy First mandate
+
+6. **Publish in dependency order:**
+   - Create blockers first, then dependents.
+   - Capture created IDs/URLs from stdout; never guess identifiers.
+   - Apply tracker labels such as `needs-triage` when the project uses them.
+   - Wire dependencies using actual captured identifiers or explicit body references.
+   - Verify each creation step succeeded before continuing.
+
+7. **Final report:**
+   - Summarize the approved slice set, created issues, labels, and dependency links.
+   - Flag any deferred HITL items or unresolved ambiguity.
+
+## Rules
+- **Tracer bullets first:** prefer many thin, complete slices over a few thick horizontal tickets.
+- **Independently valuable:** each issue should produce a testable behavior change, not just preparatory plumbing.
+- **Traceable:** reference the exact plan/spec section or story.
+- **Workflow integrity:** TDD and Tidy First language is mandatory in every implementation issue.
+- **No guessed IDs:** capture identifiers from actual command output.
+- **Stop and ask:** if the plan only supports horizontal decomposition, propose a vertical rewrite before publishing.
+
+## References
+- **Templates:** `references/templates.md`
+- **Criteria:** `references/criteria.md`

package/pi-package/skills/create-issues/references/criteria.md

@@ -0,0 +1,44 @@
+# Issue Creation Criteria
+
+Use these criteria to evaluate whether a plan has been translated into strong tracer-bullet issues.
+
+## High-Quality Issue Standards
+
+| Feature | Criteria |
+| :--- | :--- |
+| **Tracer-bullet shape** | Each issue is a thin vertical slice, not a horizontal layer ticket. |
+| **Independent value** | A completed issue is demoable, testable, or otherwise verifiable on its own. |
+| **Atomicity** | Each issue covers one logical capability. If it spans multiple unrelated behaviors, split it. |
+| **Actionable Title** | Short, specific, and domain-oriented. Prefer behavior over component names. |
+| **Traceability** | Contains a direct reference to the source plan/spec section or story. |
+| **Verifiability** | Acceptance criteria are binary and observable. |
+| **Dependency hygiene** | Only real blockers are encoded; parallel work is not serialized without reason. |
+| **Workflow Mandate** | Includes the mandatory TDD and Tidy First block. |
+| **Execution mode** | Slice is explicitly marked AFK or HITL. |
+
+## Tracer-Bullet Heuristics
+
+Use these checks before publishing:
+
+- [ ] Does this issue deliver a narrow but complete path through relevant layers?
+- [ ] Could someone demo or verify this slice without waiting for a later ticket?
+- [ ] Is this a user-visible or system-verifiable outcome rather than plumbing-only work?
+- [ ] If the ticket is preparatory, is that preparatory work itself independently valuable?
+- [ ] Would splitting by backend/frontend/schema create worse horizontal tickets than the current slice?
+
+## Dependency Reliability Checklist
+
+- [ ] All IDs captured from command output using variables.
+- [ ] Dependency commands reference the captured variables.
+- [ ] Blockers are real prerequisites, not just preferred order.
+- [ ] AFK/HITL designation is explicit.
+- [ ] Parallel work is left parallel where the tracker supports it.
+
+## When to Stop & Ask
+
+- [ ] The plan is written as phases/layers only and cannot yet be sliced vertically.
+- [ ] Acceptance criteria are too vague to make binary.
+- [ ] File paths or impacted surfaces are unknown and need discovery.
+- [ ] The target tracker is not accessible via CLI/API.
+- [ ] Existing issues already cover part of the plan and would conflict with new tickets.
+- [ ] HITL slices need human approval before publishing.

package/pi-package/skills/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/pi-package/skills/create-plan/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: create-plan
+description: "Design phased implementation plans with TDD approach"
+metadata:
+  installed-from: "incitaciones"
+---
+# 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/pi-package/skills/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/pi-package/skills/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/pi-package/skills/debug/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: debug
+description: "7-step diagnostic workflow for debugging issues"
+metadata:
+  installed-from: "incitaciones"
+---
+<!-- 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.