incitaciones 0.1.0

package/pi-package/skills/implement-plan/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: implement-plan
+description: "Execute implementation plans phase by phase"
+metadata:
+  installed-from: "incitaciones"
+---
+# Implement Plan
+
+Implement an approved plan using Red, Green, Refactor.
+
+## Procedure
+
+1. Read the plan completely and identify the first incomplete phase.
+2. Read any related specs or documentation referenced by the plan.
+3. For each phase:
+   - Write failing tests first.
+   - Implement the minimum code to pass.
+   - Refactor while keeping tests green.
+   - Run the success criteria checks.
+   - Update the plan with progress.
+4. Use `references/verification-template.md` when reporting phase completion.
+5. Use `references/common-situations.md` when the plan and reality diverge.
+
+## Rules
+
+- Never skip the red phase.
+- Complete one phase at a time.
+- Do not blindly follow an outdated plan if the codebase contradicts it.
+- Wait for user confirmation before proceeding to the next phase.

package/pi-package/skills/implement-plan/references/common-situations.md

@@ -0,0 +1,36 @@
+## Common Situations
+
+### Tests already pass
+
+- Verify the implementation really matches the plan.
+- Mark the phase complete if it does.
+
+### The plan does not match reality
+
+Report:
+
+```text
+Issue in Phase [N]:
+
+Expected (from plan): [What the plan says]
+Found (in codebase): [Actual situation]
+Why this matters: [Impact]
+
+Options:
+1. Adapt implementation to current reality
+2. Update the plan
+3. Ask the user for guidance
+```
+
+### A better approach appears mid-implementation
+
+- Explain the current plan.
+- Explain the alternative.
+- Summarize the tradeoffs.
+- Ask whether to continue or update the plan.
+
+### External dependency is unavailable
+
+- State what is blocked.
+- Explain impact.
+- List available workarounds, if any.

package/pi-package/skills/implement-plan/references/verification-template.md

@@ -0,0 +1,18 @@
+```text
+Phase [N] Complete - Ready for Verification
+
+Automated verification:
+- [x] All tests pass
+- [x] Type checking passes
+- [x] Build succeeds
+
+Manual verification needed:
+- [ ] [Manual step 1]
+- [ ] [Manual step 2]
+
+Changes made:
+- [path:line] [What changed]
+- [path:line] [What changed]
+
+Let me know when verified so I can proceed to Phase [N+1].
+```

package/pi-package/skills/invalid-states-diagnostician/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: invalid-states-diagnostician
+description: "Diagnose representable invalid states — primitive obsession, boolean blindness, implicit coupling, shotgun parsing, ad-hoc state machines, exhaustiveness gaps — and map findings to type-tightening refactoring patterns"
+metadata:
+  installed-from: "incitaciones"
+---
+<!-- Full version: content/prompt-task-invalid-states-diagnostician.md -->
+You are a Type Integrity Analyst. Diagnose locations where the type system permits business-invalid states — including primitive obsession, boolean blindness, implicit coupling, shotgun parsing, ad-hoc state machines, unconstrained optionality, exhaustiveness gaps, and monolithic records — and map each finding to a type-tightening refactoring pattern. Do NOT modify any files — advisory only.
+
+**GUARD:** Do not apply to greenfield projects, codebases without static type checking and no gradual typing in use (plain JS without TS, Python without mypy/pyright), or when the problem is mutable state/side effects (use mutability-diagnostician), structural coupling/inheritance (use rigidity-diagnostician), or composition friction (use composability-diagnostician). Domain concepts that are genuinely unconstrained strings (free-text, user notes) are not primitive obsession — only flag primitives harboring hidden business rules.
+
+**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., "TypeScript/React" — or "infer"]
+
+**PROTOCOL (Five-Step Pipeline)**
+
+Step 1 — Detect State Integrity Signals: Read all files. Identify:
+- Shotgun Parsing (Critical): validation (format checks, range checks, null guards) scattered across business logic instead of enforced at boundary; same validation duplicated in multiple locations
+- Ad-hoc State Machine (Critical): lifecycle via string comparisons, boolean flag combinations, or enum checks without structural enforcement; functions callable in semantically invalid states
+- Primitive Obsession (High): domain concepts (email, money, URL, coordinates) as raw strings/numbers without validation; implicit constraints enforced only at usage sites
+- Boolean Blindness (High): bare boolean parameters/returns with invisible meaning at call site; boolean flag clusters whose combinations produce invalid states; boolean checks disconnected from guarded data
+- Implicit Coupling (High): fields that must change together but exist independently — updating one without the other silently corrupts state
+- Exhaustiveness Gap (High): switch/match with catch-all default on types that should be exhaustively handled; missing `never`/`assert_never` guards
+- Unconstrained Optionality (High): implicit nullability without type-system-enforced null checks; Option/Maybe unwrapped deep in business logic instead of parsed at boundary
+- Monolithic Record (Medium): large records grouping unrelated fields updated independently; domain transactions forced to instantiate more data than needed
+Note file, line range, and description for each.
+
+Step 2 — Classify State Space Gap: For each signal, assess:
+- Scope: Type-local (single type too broad) / Cross-type (shared implicit coupling) / Boundary (external data enters unparsed) / System-wide (domain types exposed as API/DB schemas)
+- Invalid state count: how many representable states are business-invalid (e.g., 3 booleans = 8 states, 3 valid → 5 invalid)
+- Failure mode: silent corruption (Critical) / runtime exception (High) / logged warning (Low)
+- Validation scattering: how many locations currently guard against this invalid state at runtime
+
+Step 3 — Analyze State Space: For top 5-10 findings by severity:
+- **Finite state spaces** (boolean clusters, enum combinations): Enumerate S_repr (all states type permits), S_valid (business-legal states), S_invalid = S_repr - S_valid (states to make unrepresentable)
+- **Unbounded state spaces** (string for email, number for price): Characterize S_valid subset (e.g., "RFC 5322 email format") — do not enumerate infinite invalid space; count compensating runtime guards as primary severity metric
+- For all findings: locate compensating validation for each invalid state — count guard locations
+
+Step 4 — Map to Refactoring Pattern:
+- Domain concepts as raw primitives → **Value Object (Tiny Type)**: self-validating, immutable; invalid data fails construction
+- Bare booleans for domain states → **Semantic Enum / Discriminated Union**: `Permission.ReadOnly | Permission.ReadWrite` not `(bool, bool)`
+- Coupled fields existing independently → **Atomic Record**: group into single type updated as transactional unit
+- Unrelated fields over-grouped → **Context-Specific Decomposition**: split into bounded types per usage context
+- Validation scattered across layers → **Parse at the Boundary**: "Parse, Don't Validate" — transform external data to strict domain types at edge
+- Lifecycle managed by flags/strings → **Typestate Pattern**: distinct type per state; invalid transitions are compiler errors
+- Missing exhaustive handling → **Exhaustiveness Enforcement**: remove defaults, add `never`/`assert_never`; omit `default` on sealed switches (Java)
+- Implicit nullability → **Explicit Optionality with Boundary Parsing**: Option/Maybe with strict null checks; unwrap at boundary only
+
+Native equivalents: Value Object → `record` (C#/Java), `data class` (Kotlin), newtype (Rust), branded types (TS); Discriminated Union → `enum` with data (Rust/Swift), `sealed interface` (Java/Kotlin), discriminated union (F#/TS); Typestate → `PhantomData` (Rust), sealed hierarchies (Kotlin/Java), discriminated union (TS — simple) or branded types (TS — advanced); Exhaustiveness → `never` (TS), `assert_never()` (Python), omit `default` on sealed switches (Java); Boundary Parsing → Zod/io-ts (TS), Pydantic (Python), serde (Rust), `System.Text.Json` (C#).
+
+Step 5 — Prioritize: Score = State Space Gap (System-wide=3, Boundary/Cross-type=2, Type-local=1) x Failure Severity (Silent corruption/security=3, Runtime exception=2, Cosmetic=1) x Validation Scattering (3+ guards=3, 2 guards=2, Single/none=1). Sequence: Value Objects first (smallest, safest, collapses scattered validation), boundary parsing next (prevents new invalid data entering), semantic enums and exhaustiveness follow (eliminates boolean blindness), atomic records and decompositions next (structural grouping), typestate last (highest architectural impact). Each step independently deployable.
+
+**OUTPUT**
+
+Summary table:
+| Location | State Integrity Signal | State Space Gap | S_invalid Count | Refactoring Pattern | Priority |
+
+If multiple signals share root cause, consolidate. Then per finding: signal (files, lines, names), state space gap (S_repr vs S_valid — which states are invalid, how many guards compensate), recommended pattern (sketch, not full code), refactoring sequence (safe steps), success signals (domain types rejecting invalid state at construction, switch statements breaking at compile time on new variants, boundary parsers transforming chaos into axioms).
+
+Enforcement recommendations per language: TS → `strictNullChecks`, `noUncheckedIndexedAccess`, Zod at boundaries, `never` default; Rust → `clippy::all` + `clippy::pedantic`, exhaustive match; Java → sealed interfaces, no `default` on sealed switches, ArchUnit for encapsulation; C#/.NET → NetArchTest (no parameterless constructors, no public setters on domain types), `record` with `init`; Python → `mypy --strict`, `assert_never()`, Pydantic at boundaries. Unlisted: Kotlin (`sealed class`, `when` exhaustiveness), Swift (exhaustive `switch`), F# (discriminated unions), Go (unexported fields + constructors).
+
+Needs Human Review: list ambiguous cases — genuinely unconstrained strings (free-text, notes), boolean flags required by framework conventions (serialization, ORM), boundary schemas where strict typing conflicts with backwards compatibility (enforce internally via "Parse, Don't Validate", keep external schemas permissive), state machines in high-variance domains where bidirectional transitions are business requirements, unsigned vs signed integer choices (unsigned arithmetic can underflow to dangerous positive values), performance-critical hot paths where Value Object allocation overhead matters.
+
+If no signals found: "No representable invalid states found. Domain types accurately constrain their business meaning, boundaries parse external data into strict types, and state transitions are structurally enforced." Do not fabricate findings.
+
+Stop when all files analyzed. Do not modify anything.

package/pi-package/skills/issue-review/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: issue-review
+description: "Review issues for completeness and dependencies"
+metadata:
+  installed-from: "incitaciones"
+---
+# Tracer-Bullet Issue Review (Rule of 5)
+
+Review an issue set in five passes, with special attention to whether tickets are true tracer-bullet vertical slices.
+
+## Setup
+
+Read `references/setup.md` for tracker-specific collection commands before reviewing.
+
+## Procedure
+
+1. Gather the issue set to review plus the source plan/spec/parent issue when available.
+2. Run the passes in order:
+   - Pass 1: `references/pass-1-clarity.md`
+   - Pass 2: `references/pass-2-scope.md`
+   - Pass 3: `references/pass-3-dependencies.md`
+   - Pass 4: `references/pass-4-alignment.md`
+   - Pass 5: `references/pass-5-executability.md`
+3. After each pass starting with pass 2, evaluate convergence using `references/convergence.md`.
+4. If converged, stop.
+5. Produce the final report using `references/final-report.md`.
+
+## Review Lens
+
+Treat the best issue sets as:
+- thin vertical slices rather than layer tickets
+- independently verifiable or demoable
+- minimal but sufficient dependency graphs
+- explicit about AFK vs HITL work
+- traceable back to stories, plans, or specs
+
+## Rules
+
+- Reference issue IDs precisely.
+- Verify issue content before flagging a problem.
+- Prioritize blockers over cosmetic cleanup.
+- Suggest exact tracker edits or commands when practical.
+- Call out horizontal decomposition explicitly: backend-only, schema-only, UI-only, or refactor-only tickets that should be folded into a tracer bullet.

package/pi-package/skills/issue-review/references/convergence.md

@@ -0,0 +1,19 @@
+## Convergence Check
+
+After each pass starting with pass 2, report:
+
+```text
+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]
+```
+
+Criteria:
+- `CONVERGED`: no new CRITICAL issues, <10% new issues vs previous pass, <20% false positives
+- `ITERATE`: continue
+- `NEEDS_HUMAN`: blocking judgment call required

package/pi-package/skills/issue-review/references/final-report.md

@@ -0,0 +1,60 @@
+## Final Report Template
+
+```text
+## Issue Tracker Review Final Report
+
+System: [Beads/GitHub/Linear/Jira]
+Scope: [All issues / Milestone / Label set]
+Source: [Plan/spec/parent issue if known]
+
+### Summary
+
+Total Issues Reviewed: [count]
+
+Issues Found by Severity:
+- CRITICAL: [count]
+- HIGH: [count]
+- MEDIUM: [count]
+- LOW: [count]
+
+Convergence: Pass [N]
+
+### Tracer-Bullet Assessment
+
+- Slice quality: [Excellent|Good|Fair|Poor]
+- Horizontal-ticket leakage: [None|Low|Moderate|High]
+- AFK/HITL clarity: [Excellent|Good|Fair|Poor]
+
+### Top 3 Most Critical Findings
+
+1. [ID] [Finding]
+   - Impact: [Why it blocks or degrades execution]
+   - Fix: [Exact command or edit]
+
+2. [ID] [Finding]
+   - Impact: [Why it matters]
+   - Fix: [Exact command or edit]
+
+3. [ID] [Finding]
+   - Impact: [Why it matters]
+   - Fix: [Exact command or edit]
+
+### Recommended Actions
+
+- Provide exact tracker commands where practical.
+- Collapse horizontal tickets into tracer bullets when possible.
+- Include file paths, tests, and plan/story references when missing.
+
+### Verdict
+
+[READY_TO_WORK | NEEDS_UPDATES | NEEDS_REPLANNING]
+
+Rationale: [1-2 sentences]
+
+### Issue Quality Assessment
+
+- Clarity: [Excellent|Good|Fair|Poor]
+- Scope: [Excellent|Good|Fair|Poor]
+- Dependencies: [Excellent|Good|Fair|Poor]
+- Completeness: [Excellent|Good|Fair|Poor]
+```

package/pi-package/skills/issue-review/references/pass-1-clarity.md

@@ -0,0 +1,28 @@
+## Pass 1: Completeness and Clarity
+
+Focus on:
+- Clear title
+- Sufficient context
+- Concrete file paths and changes
+- Success criteria or tests
+- Unambiguous done criteria
+
+Watch for:
+- Vague titles
+- Minimal descriptions
+- "Implement X" without where or how
+- Missing verification steps
+
+Output:
+
+```text
+PASS 1: Completeness & Clarity
+
+Issues Found:
+
+[CLRT-001] [CRITICAL|HIGH|MEDIUM|LOW] - Issue ID/Number
+Title: [Issue title]
+Description: [What's unclear or incomplete]
+Evidence: [Why this is a problem]
+Recommendation: [How to fix]
+```

package/pi-package/skills/issue-review/references/pass-2-scope.md

@@ -0,0 +1,22 @@
+## Pass 2: Scope, Atomicity, and Tracer-Bullet Shape
+
+Focus on:
+- One logical capability per issue
+- Thin vertical slices instead of horizontal layer tickets
+- Issues small enough to finish in one focused session
+- Clear boundaries with no overlap
+- Independent demo or verification value
+
+Watch for:
+- Oversized epics disguised as issues
+- Backend-only / schema-only / UI-only tickets that should be part of one slice
+- Preparatory plumbing tickets with no standalone value
+- Trivial issues that should be bundled into a slice
+- Refactor + feature bundles with unclear boundaries
+
+Questions to ask:
+- If this issue lands alone, is anything real now possible or testable?
+- Does it cut through the necessary layers for one outcome?
+- Would splitting it by component create worse tickets?
+
+Prefix findings with `SCOPE-`.

package/pi-package/skills/issue-review/references/pass-3-dependencies.md

@@ -0,0 +1,23 @@
+## Pass 3: Dependencies and Ordering
+
+Focus on:
+- Correct dependency links
+- Missing prerequisites
+- Circular dependencies
+- Avoidable serialization
+- Sensible critical path
+- Whether the issue graph reflects tracer bullets rather than phase gates
+
+Watch for:
+- Hidden blockers
+- Cycles
+- Artificial bottlenecks from horizontal decomposition
+- Missing rationale for dependencies
+- Tickets blocked only because the work was split by layer instead of by outcome
+
+Questions to ask:
+- Could these issues run in parallel if they were sliced vertically?
+- Is a dependency real, or an artifact of poor decomposition?
+- Are HITL issues isolated so AFK work can continue around them?
+
+Prefix findings with `DEP-`.

package/pi-package/skills/issue-review/references/pass-4-alignment.md

@@ -0,0 +1,17 @@
+## Pass 4: Plan, Story, and Spec Alignment
+
+Focus on:
+- Traceability to plan/spec sections or user stories
+- Coverage of the intended workflow end-to-end
+- Alignment between the chosen issue breakdown and the source material
+- Explicit tests before implementation
+- AFK/HITL classification when relevant
+
+Watch for:
+- Missing plan or story references
+- Gaps where a user story is only partially covered across layer tickets
+- Specs with no corresponding issue
+- Issues that contradict the intended implementation approach
+- Breakdown by phase/component when the source material describes user outcomes
+
+Prefix findings with `ALIGN-`.

package/pi-package/skills/issue-review/references/pass-5-executability.md

@@ -0,0 +1,17 @@
+## Pass 5: Executability and Handoff
+
+Focus on:
+- Can another developer or agent pick this up immediately?
+- Are verification steps concrete and end-to-end?
+- Are priorities and labels sensible?
+- Are HITL handoff points explicit?
+- Is it clear what demo, test, or observable behavior proves completion?
+
+Watch for:
+- Hidden conversational context
+- "You know what to do"
+- Missing verification commands or test references
+- HITL work masquerading as AFK
+- Tickets that cannot be closed without information from another issue not listed as a blocker
+
+Prefix findings with `EXEC-`.

package/pi-package/skills/issue-review/references/setup.md

@@ -0,0 +1,25 @@
+## Gathering Issues to Review
+
+### Beads
+
+```bash
+bd list
+bd ready
+bd graph
+bd show <id>
+bd dep tree
+bd dep cycles
+```
+
+### GitHub Issues
+
+```bash
+gh issue list --label "needs-review" --json number,title,body,labels
+gh issue view <number>
+```
+
+### Other systems
+
+- Export issues to JSON or CSV.
+- Use available CLI or API tooling.
+- Require issue data as input before reviewing.

package/pi-package/skills/iterate-plan/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: iterate-plan
+description: "Refine and improve existing plans based on feedback"
+metadata:
+  installed-from: "incitaciones"
+---
+# Iterate Implementation Plan
+
+Update an existing implementation plan based on feedback and current codebase reality.
+
+## Procedure
+
+1. Read the current plan completely.
+2. Understand the requested changes.
+3. Research only if the requested change requires new technical context.
+4. Confirm your understanding with the user before editing.
+5. Make focused updates to the plan.
+6. Present the changes and iterate until approved.
+
+## Rules
+
+- Preserve completed work unless the user explicitly wants to revise it.
+- Prefer surgical edits over wholesale rewrites.
+- Ask normal clarifying questions if the request is ambiguous.
+- If the plan needs substantial restructuring, recommend creating a new plan.
+
+## References
+
+- Use `references/change-template.md` when summarizing planned edits.
+- Use `references/common-scenarios.md` for common iteration patterns.

package/pi-package/skills/iterate-plan/references/change-template.md

@@ -0,0 +1,15 @@
+```text
+Based on your feedback, I understand you want to:
+- [Change 1]
+- [Change 2]
+
+[If research was done]
+My research found:
+- [Relevant pattern or constraint]
+
+I plan to update the plan by:
+1. [Specific modification]
+2. [Specific modification]
+
+Does this align with your intent?
+```

package/pi-package/skills/iterate-plan/references/common-scenarios.md

@@ -0,0 +1,14 @@
+## Common Iteration Scenarios
+
+- Adding a new phase
+- Changing the implementation approach
+- Adding missing detail
+- Removing scope
+- Splitting an oversized phase
+- Correcting a technical error
+
+For each case:
+- identify the affected sections,
+- research only what changed,
+- update success criteria and dependencies if needed,
+- preserve completed work.

package/pi-package/skills/julia-performance-diagnostician/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: julia-performance-diagnostician
+description: "Diagnose Julia performance pathologies — type instabilities, heap allocation floods, cache-hostile access, dynamic dispatch — and map findings to optimization patterns grounded in the compilation pipeline"
+metadata:
+  installed-from: "incitaciones"
+---
+<!-- Full version: content/prompt-task-julia-performance-diagnostician.md -->
+You are a Julia Performance Analyst. Diagnose performance pathologies — type instabilities, heap allocation floods, cache-hostile memory access, dynamic dispatch overhead, and type system misuse — and map each finding to a specific optimization pattern grounded in Julia's compilation pipeline. Do NOT modify any files — advisory only.
+
+**GUARD:** Do not apply when the problem is algorithmic complexity rather than Julia-specific pathology, when the codebase already passes JET.jl and AllocCheck.jl cleanly, or for distributed computing (MPI.jl/Distributed.jl) issues. Union return types with 2-3 variants may be handled efficiently by union-splitting — only flag unions with 4+ variants or in hot loops. Local mutation (loop accumulators, pre-allocated buffers) is idiomatic Julia — only flag mutation that causes type instability or allocation.
+
+**INPUT**
+- Target files/directory: [SPECIFY]
+- Benchmark baseline (optional): [@time or @btime output OR "none"]
+- @code_warntype output (optional): [PASTE OR "none"]
+- High-churn files (optional): [git log output OR "none"]
+- Julia version (optional): [e.g., "1.10" — or "infer from Project.toml"]
+
+**PROTOCOL (Five-Step Pipeline)**
+
+Step 1 — Detect Performance Signals: Read all files. Identify:
+- Type Instability / Unnecessary Boxing (Critical): return type or internal variables depend on runtime values, not argument types; conditionals returning different types; `Union` types wider than 3-4 variants; frequent numeric type conversions mid-computation; `Any`/`Union` in `@code_warntype`
+- Untyped Global Variable (Critical): module-level variables without `const` read inside functions — compiler abandons inference entirely
+- Abstract Container Parameter (High): `Vector{Real}`, `Array{Any}`, `Dict{String, Any}` — forces pointer-based storage, destroys contiguous layout
+- Abstractly-Typed Struct Field (High): `data::AbstractArray` without type parameterization — every field access requires dispatch
+- Cache-Hostile Memory Access (High): inner loops varying second+ index on multidimensional arrays — violates column-major, causes cache misses
+- Heap Allocation in Hot Loop (High): `x[2:end]` without `@views`, string concatenation, temporary objects inside tight loops
+- Dynamic Dispatch in Hot Path (High): function calls on abstract-typed values in loops — blocks inlining and SIMD
+- GPU Scalar Indexing (Critical): element-by-element CuArray access in loops — kernel launch + PCIe transfer per element
+- Missing Function Barrier (Medium): computation immediately after dynamic parsing (JSON/CSV) — entire block inherits instability
+- Deep Recursion (Medium): recursive algorithms without depth bounds — Julia lacks guaranteed TCO
+- Dict for Static Keys (Medium): `Dict` with compile-time-known keys — runtime hashing vs. zero-cost NamedTuple
+Note file, line range, and description for each.
+
+Step 2 — Classify Performance Impact: For each signal, assess:
+- Scope: Hot Loop (Critical) / Per-Call (High) / Initialization (Low) / API Boundary (High — propagates to callers)
+- Allocation impact: heap allocs in loop? (Critical if yes — floods GC)
+- Dispatch impact: forces dynamic dispatch? (High if blocks inlining/SIMD)
+- Cache impact: causes cache misses? (High for strided access or pointer-chasing through boxed values)
+
+Step 3 — Analyze Type Flow: For each flagged function, trace type inference:
+- Return type stability: does return type depend solely on argument types?
+- Internal groundedness: are all internal variables inferrable? (red in `@code_warntype` even if return is stable = intermediate boxing)
+- Caller propagation: do callers inherit the instability?
+- Container element types: concrete or abstract parameterization?
+- Memory layout: column-major access in loop nests?
+Describe type flow for top 5-10 functions by severity.
+
+Step 4 — Map to Optimization Pattern:
+- Type-unstable return → **Type-Stable Refactoring**: ensure all paths return same concrete type
+- Untyped global → **Const Declaration / Encapsulation**: `const` to freeze binding, or wrap in function + pass as argument, or annotate `local_x = global_x::ConcreteType`
+- Abstract container → **Concrete Parameterization**: `Vector{Float64}` instead of `Vector{Real}`
+- Abstract struct field → **Parametric Struct**: `struct S{T<:AbstractArray} data::T end`
+- Cache-hostile loop → **Column-Major Reordering**: innermost loop varies first index; use `eachcol`/`eachrow`; `@views` for slicing
+- Allocs in hot loop → **@views + In-Place Operations**: `@views`, `mul!`/`ldiv!`, pre-allocate buffers outside loop
+- Dynamic dispatch in hot path OR dynamic data → computation → **Function Barrier**: extract loop/kernel into separate function receiving concrete-typed args; for parsed data (JSON/CSV), convert at boundary: `_kernel(Float64(cfg["dt"]), ...)`
+- GPU scalar indexing → **Bulk Broadcasting**: `.=`, `map`; enforce `GPUArraysCore.allowscalar(false)`
+- Deep recursion → **Explicit Loop + Accumulator**: `for`/`while` with function-barrier widening for type-varying accumulation
+- Dict for static config → **NamedTuple / Struct**: `(; key=val)` — zero-cost, stack-allocated
+- Missing SIMD → **Dot-Syntax Broadcasting / @simd**: `A .= B .+ C .* D` for loop fusion; `@simd` for explicit vectorization; `@turbo` only for proven bottlenecks with non-aliasing guarantee (verify LoopVectorization.jl compatibility)
+
+Step 5 — Prioritize: Score = Allocation Impact (Loop allocs=3, Per-call=2, None=1) × Dispatch Impact (Dynamic=3, Partial=2, Mono=1) × Scope (Hot loop=3, Per-call/API=2, Init=1). Sequence: type stability fixes first (unblock all downstream opts), global elimination next (largest single-fix gain), concrete parameterization (contiguous layout), function barriers (isolate instability), memory reordering + @views (cache + GC), SIMD/broadcasting last (polish). Each fix independently deployable and benchmarkable.
+
+**OUTPUT**
+
+Summary table:
+| Location | Performance Signal | Impact Scope | Type Flow | Optimization Pattern | Priority |
+
+If multiple signals share root cause, consolidate. Then per finding: signal (files, lines, function names, type signatures), impact scope (allocation/dispatch/cache impact), type flow analysis (inference chain showing where stability breaks), recommended pattern (sketch, not full code), verification method (specific `@code_warntype`, `@btime`, `@allocated`, JET.jl, or AllocCheck.jl invocations), optimization sequence (safe steps), success signals (`@code_warntype` all concrete, `@btime` zero allocs, profiler shows computation not GC/dispatch).
+
+Tooling recommendations per finding category: type instability → `@code_warntype`; call-tree → Cthulhu.jl `@descend`; whole-module → JET.jl `@report_opt`; allocation count → `@btime` with `$`-interpolation; allocation source → `@profview_allocs`; zero-alloc proof → AllocCheck.jl `@check_allocs`; CI regression → AirspeedVelocity.jl.
+
+Needs Human Review: list ambiguous cases — type instabilities in cold paths, small `Union` types where union-splitting suffices, mutable pre-allocated buffers (idiomatic), `@turbo` compatibility concerns, intentional `allowscalar(true)` for debugging, struct parameterization risking compilation explosion, intentionally generic functions for dispatch extensibility, multi-threaded code (`Threads.@threads`/`@spawn`) where data races or false sharing are outside this diagnostic's scope.
+
+If no signals found: "No performance pathologies found. Functions are type-stable, containers use concrete parameters, memory access follows column-major ordering, and hot loops are allocation-free." Do not fabricate findings.
+
+Stop when all files analyzed. Do not modify anything.

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

@@ -0,0 +1,74 @@
+---
+name: modularity-diagnostician
+description: "Diagnose modularity violations — high coupling, low cohesion, cyclic dependencies, God Objects, boundary erosion, temporal coupling — and map findings to decomposition patterns grounded in the Unix philosophy"
+metadata:
+  installed-from: "incitaciones"
+---
+<!-- Full version: content/prompt-task-modularity-diagnostician.md -->
+You are a Software Modularity Analyst. Diagnose modularity violations — high coupling, low cohesion, cyclic dependencies, God Objects, boundary erosion, temporal coupling — and map each finding to a decomposition or restructuring pattern grounded in the Unix philosophy of "Do One Thing And Do It Well." Do NOT modify any files — advisory only.
+
+**GUARD:** Do not apply to greenfield projects or when the problem is composition friction in pipelines (use composability-diagnostician), mutable state entanglement (use mutability-diagnostician), or structural rigidity from inheritance (use rigidity-diagnostician). Requires accumulated integration surface to diagnose.
+
+**INPUT**
+- Target files/directory: [SPECIFY]
+- High-churn files (optional): [git log output OR "none"]
+- Co-change data (optional): [co-change analysis output OR "none"]
+- Architecture reference (optional): [AGENTS.md rules OR "none"]
+- Language/framework (optional): [e.g., "Python/Django" — or "infer"]
+
+**PROTOCOL (Five-Step Pipeline)**
+
+Step 1 — Detect Modularity Signals: Read all files. Identify:
+- God Object / God Class (Critical): excessive responsibilities — high method/attribute count, LCOM violation showing methods operate on disjoint state subsets, modified for multiple unrelated reasons
+- Cyclic Dependency (Critical): Module A → B → C → A. Makes isolated extraction, testing, and deployment impossible. Dependency graph must form a DAG
+- Shotgun Surgery (High): single logical change requires modifications scattered across many files in different modules — things that change together not packaged together
+- Divergent Change (High): single class modified for entirely different reasons (e.g., authentication changes AND email format changes)
+- Feature Envy (High): method interacts more with another class's data than its own — suggests method belongs elsewhere
+- Inappropriate Intimacy (High): two classes overly reliant on each other's internal details, breaking encapsulation
+- High Efferent Coupling (Medium): module depends on many externals — fragile, many import statements spanning packages
+- High Afferent Coupling (Medium): module depended upon by many consumers — alterations trigger widespread ripple effects
+- Temporal Coupling (Medium): files co-changing in commits despite no static dependency — reveals hidden dependencies (skip if no git/co-change data provided)
+- Missing Boundary (Medium): related functionality spread across modules with no clear owning package
+Note file, line range, and description for each.
+
+Step 2 — Classify Modularity Scope: For each signal, assess:
+- Scope: Local (within class) / Module (within package) / Cross-Module (between packages/layers) / System-Wide (affects entire topology)
+- Change amplification: how many files change for a single requirement? (High if >5 files across >2 modules)
+- Extraction difficulty: could this module be extracted today? (Blocked / Hard / Moderate / Easy)
+- Test isolation: can the module be unit tested without mocking >3 external dependencies? (Poor if excessive mocking — flag as risk)
+
+Step 3 — Analyze Dependency Structure: Map relationships between modules:
+- Map `A → B`, `B → C`, etc. Flag bidirectional or cyclic dependencies
+- Compute Instability Index per module: `I = Ce / (Ca + Ce)`. Flag unstable modules at the foundation or stable modules at the periphery
+- Assess cohesion: do methods within each class share state or operate on disjoint subsets? (LCOM violation if disjoint)
+- Assess boundary clarity: do callers use a public API/interface or reach into internal implementation?
+Draw dependency map for top 5-10 modules by severity, identifying cut points.
+
+Step 4 — Map to Remediation Pattern:
+- God Object centralizing multiple responsibilities → **Extract Class / Extract Module**: identify method clusters via attribute access analysis; extract each cluster into cohesive class with single responsibility
+- Cyclic dependency between modules → **Dependency Inversion + Interface Extraction**: introduce interface owned by depended-upon module; invert one edge direction to break cycle
+- Shotgun Surgery across modules → **Move Method / Move Class to Owning Module**: relocate scattered logic into domain-owning module. Create new bounded context if none exists
+- Divergent Change in single class → **Split by Reason for Change**: identify distinct axes of change, extract each into own class/module
+- Feature Envy → **Move Method**: relocate method to class whose data it primarily accesses
+- Inappropriate Intimacy → **Encapsulate Field + Extract Interface**: hide internals behind methods; extract minimal cross-class interface
+- High Ce → **Facade / Adapter Consolidation**: consolidate external dependencies behind single interface
+- High Ca → **Interface Segregation**: split public API into role-specific interfaces so consumers depend only on what they use
+- Temporal coupling without static dependency → **Colocate Co-Evolving Code**: move co-changing files to same module, or make dependency explicit via interface/event contract
+- Missing boundary → **Extract Bounded Context**: aggregate domain-related code into new cohesive module with clear public API
+
+Step 5 — Prioritize: Score = Change Amplification (>10 files=3, 5-10=2, <5=1) × Extraction Difficulty (Blocked=3, Hard=2, Moderate/Easy=1) × Modularity Scope (System-wide=3, Cross-module=2, Module/Local=1). Sequence: break cycles first (unblocks all extractions), God Object decomposition next (largest modularity gain), Shotgun Surgery consolidation (groups co-changing code), interface extractions (stabilize boundaries), temporal coupling resolution last (requires team negotiation). Each step independently deployable.
+
+**OUTPUT**
+
+Summary table:
+| Location | Modularity Signal | Modularity Scope | Dependency Structure | Remediation Pattern | Priority |
+
+If multiple signals share root cause, consolidate. Then per finding: signal (files, lines, import chains), modularity scope (propagation + change amplification/extraction difficulty/test isolation), dependency structure (coupling map with direction, cycles, instability scores, cut points), recommended pattern (sketch, not full code), metrics to track (CBO ≤ 9, LCOM-HS ≤ 30%, Instability targets), remediation sequence (safe steps), success signals (modules extractable independently, changes localized, dependency graph forms DAG).
+
+Needs Human Review: list ambiguous cases — God Objects that are intentional facades/orchestrators, temporal coupling reflecting legitimate business transactions, high Ca modules that are stable shared libraries, framework-mandated cross-module dependencies, modules mid-migration.
+
+If no signals found: "No modularity violations found. Modules have clear boundaries, dependencies flow unidirectionally, cohesion is high within each component, and changes are localized." Do not fabricate findings.
+
+Tooling: SonarQube/JDepend/NDepend (CBO, LCOM, Ca/Ce threshold gates in CI), ArchUnit/archunit-ts (boundary enforcement as executable unit tests), CodeScene/code-maat (temporal coupling and hotspot monitoring).
+
+Stop when all files analyzed. Do not modify anything.