@needfspeed/skills-library 0.2.0 → 0.3.0

package/skills/pstack/how/references/critique-rubric.md

@@ -1,58 +0,0 @@
-# Architectural Critique Rubric
-
-Review through whichever of these lenses are relevant. Not every lens applies to every subsystem.
-
-## Abstraction Fit
-
-Are the abstractions pulling their weight?
-
-- Does each abstraction represent a real concept, or is it an indirection layer "in case we need it"?
-- Are the boundaries in the right place? Do they separate things that change independently?
-- Is there accidental coupling where components share implementation details they shouldn't need to know about?
-- Is business logic entangled with framework wiring, or cleanly separated?
-
-Over-abstraction is as much a problem as under-abstraction. A flat, simple design is fine when the domain is simple.
-
-## Data Model
-
-Do the data structures fit the actual usage patterns?
-
-- Are the data models designed for how data is actually accessed, or for how it was conceptually modeled?
-- Are there impedance mismatches, places where code constantly reshapes data because the model doesn't match the access pattern?
-- Are types honest? Do they represent what data actually looks like at runtime, or claim more structure than exists?
-
-## Boundary Discipline
-
-Are system boundaries clean and well-placed?
-
-- Is validation concentrated at entry points, or scattered through internal code?
-- Are errors handled at boundaries and propagated cleanly, or caught and re-thrown at every layer?
-- Does data cross boundaries in well-typed shapes, or as bags of optional fields?
-- Could this subsystem be tested in isolation, or does it require the entire system to be running?
-
-## Evolution Readiness
-
-How well will this architecture handle likely changes?
-
-- If the most probable next requirement landed tomorrow, how much would change? "One file" or "everything"?
-- Are there hardcoded assumptions that would need to be relaxed?
-- Is the design bolted-on (integrated as an afterthought) or integrated (looks like it was always part of the plan)?
-- Are legacy paths preserved for compatibility that no one depends on?
-
-Don't penalize for not handling hypothetical changes. Focus on changes plausible given the codebase's trajectory.
-
-## Complexity vs. Value
-
-Is the complexity budget spent wisely?
-
-- Is complexity concentrated in the parts that need it (core logic, tricky invariants) or in accidental places (boilerplate, unnecessary indirection, configuration)?
-- Are there simpler ways to achieve the same behavior?
-- Does every component earn its existence, or are there vestigial pieces from an earlier design?
-
-## Consistency
-
-Does this subsystem follow the patterns established elsewhere in the codebase?
-
-- Are similar problems solved the same way here as elsewhere, or does this area invent its own patterns?
-- If the patterns differ, is there a good reason, or did it just evolve independently?
-- Inconsistency isn't automatically bad. But unexplained inconsistency is a maintenance burden.

package/skills/pstack/interrogate/references/code-quality-review.md

@@ -1,47 +0,0 @@
-# Code Quality Review
-
-Each reviewer applies this code-quality lens in addition to the rubric. It is a strict standard focused on implementation quality, maintainability, abstraction quality, and codebase health.
-
-Above all, be ambitious about code structure. Do not merely identify local cleanup. Actively search for "code judo" moves, restructurings that preserve behavior while making the implementation dramatically simpler, smaller, more direct, and more elegant.
-
-## Core Prompt
-
-Start from this baseline:
-
-> Perform a deep code quality audit of the current branch's changes.
-> Rethink how to structure / implement the changes to meaningfully improve code quality without impacting behavior.
-> Work to improve abstractions, modularity, reduce Spaghetti code, improve succinctness and legibility.
-> Be ambitious, if there is a clear path to improving the implementation that involves restructuring some of the codebase, go for it.
-> Be extremely thorough and rigorous. Measure twice, cut once.
-
-## Dimensions
-
-Each dimension is stated once. Apply the ones that are relevant.
-
-0. **Be ambitious about structural simplification.** Do not stop at "this could be a bit cleaner." Look for reframings that make whole branches, helpers, modes, conditionals, or layers disappear. Assume a "code judo" move is often available. It uses the existing architecture more effectively and makes the change dramatically simpler. If you can delete complexity rather than rearrange it, push hard for that.
-
-1. **Do not let a PR push a file from under 1k lines to over 1k lines without a very strong reason.** Treat this as a strong smell. Prefer extracting helpers, subcomponents, or modules. If the diff crosses that threshold, ask whether the code should be decomposed first. Waive only for a compelling structural reason where the resulting file stays clearly organized.
-
-2. **Do not allow spaghetti growth in existing code.** Be suspicious of new ad-hoc conditionals, scattered special cases, or one-off branches inserted into unrelated flows. Treat "weird if statements in random places" as a design problem, not a style nit. Prefer pushing the logic into a dedicated helper, state machine, or module instead of tangling an existing path.
-
-3. **Bias toward cleaning the design, not just accepting working code.** If behavior can stay the same while the structure becomes meaningfully cleaner, push for the cleaner version. Prefer simplifications that remove moving pieces over refactors that spread the same complexity around.
-
-4. **Prefer direct, boring, maintainable code over hacky or magical code.** Treat brittle, ad-hoc, or "magic" behavior as a problem. Be skeptical of generic mechanisms that hide simple data-shape assumptions. Flag thin abstractions, identity wrappers, or pass-through helpers that add indirection without buying clarity.
-
-5. **Push on type and boundary cleanliness when it affects maintainability.** Question unnecessary optionality, `unknown`, `any`, or cast-heavy code when a clearer type boundary could exist. Prefer explicit typed models over loosely-shaped ad-hoc objects. If a branch leans on a silent fallback to paper over an unclear invariant, ask whether the boundary should be made explicit.
-
-6. **Keep logic in the canonical layer and reuse existing helpers.** Call out feature logic leaking into shared paths or implementation details leaking through APIs. Prefer existing canonical utilities over bespoke one-offs. Push code toward the right package, service, or module instead of normalizing drift.
-
-7. **Treat unnecessary sequential orchestration and non-atomic updates as design smells when the cleaner structure is obvious.** If independent work is serialized for no reason, ask whether it should run in parallel. If related updates can leave state half-applied, push for a more atomic structure. Do not over-index on micro-optimizations, but do flag avoidable orchestration complexity that makes the code more brittle.
-
-## Output Expectations
-
-Prioritize structural code-quality regressions and missed simplifications first, then spaghetti and branching complexity, then boundary, type, and file-size concerns, then smaller modularity and legibility issues. Do not flood the review with low-value nits when larger structural issues exist. Prefer a few high-conviction comments over a long list of cosmetic notes.
-
-## Approval Bar
-
-Do not approve merely because behavior seems correct. Treat these as presumptive blockers unless the author can justify them: the PR keeps a lot of incidental complexity when a code-judo move would delete it; pushes a file from below 1000 lines to above 1000 lines; adds ad-hoc branching that tangles an existing flow; scatters feature checks across shared code; adds an unnecessary abstraction, wrapper, or cast-heavy contract; or duplicates an existing helper or puts logic in the wrong layer when there is a clear canonical home. If those conditions are not met, leave explicit, actionable feedback and push for a cleaner decomposition.
-
-## Review Tone
-
-Be direct, serious, and demanding about quality. Do not be rude, but do not soften major maintainability issues into mild suggestions. If the code is making the codebase messier, say so. If the implementation missed an obvious dramatic simplification, say that too. Do not be satisfied with "maybe rename this" when the real issue is structural.

package/skills/pstack/interrogate/references/lead-judgment.md

@@ -1,58 +0,0 @@
-# Lead Judgment Framework
-
-You are the lead reviewer. The model reviewers have produced their findings. Apply pragmatic engineering judgment. Don't aggregate; filter, contextualize, and decide.
-
-## Why This Step Matters
-
-Adversarial reviewers are useful because they're aggressive. But aggression without context produces noise. The reviewers only saw a slice of the codebase and a one-paragraph intent statement. They don't know:
-
-- What was already tried and rejected
-- What constraints exist outside the code (timeline, dependencies, migration plans)
-- Which parts of the code are temporary scaffolding vs. permanent architecture
-- What the next PR in the stack will address
-
-You have the full conversation context. Use it.
-
-## Filtering Principles
-
-### Nitpick Gravity
-
-Reviewers, especially adversarial ones, tend to fill their review. If they don't find critical issues, they'll inflate nits to fill the space. If a reviewer's findings are all nits and style preferences, the code is probably fine. Say so.
-
-### Hypothetical vs. Actual
-
-"What if someone passes null here?" is only a finding if the caller can actually pass null. Trace the call site. If the input is validated upstream or the type system prevents it, dismiss the finding. Reviewers working from a diff can't always see the full call chain. You can.
-
-### Premature Abstraction Warnings
-
-Reviewers often suggest extracting functions, adding interfaces, or creating abstractions. Does this code need to change in a second way? If not, the abstraction is premature. Simple inline code that works beats a clean abstraction that's overkill for the current scope.
-
-### "I Would Have Done It Differently"
-
-This is the most common false positive in code review. A finding that amounts to "I prefer a different approach" is not a bug, not a design flaw, and not actionable unless the reviewer shows a concrete problem with the current approach. Dismiss these, and say why.
-
-### Missing Context Signals
-
-Watch for findings that reveal the reviewer didn't understand the context:
-- Suggesting changes to code the author didn't write or modify
-- Flagging patterns that are consistent with the rest of the codebase (the reviewer just doesn't know that)
-- Recommending approaches that conflict with constraints you know about
-
-These are honest mistakes from reviewers working with limited information. Dismiss them gracefully.
-
-## When Reviewers Are Right
-
-Don't dismiss findings just because they're uncomfortable. The whole point of adversarial review is to catch things you'd miss. Signs a finding deserves attention:
-
-- Multiple models flag the same issue independently (consensus signal)
-- The finding identifies a concrete execution path, not a hypothetical
-- The finding reveals a gap in your mental model of the code
-- You read the finding and think "...yeah, actually"
-
-Be especially careful about dismissing security findings and correctness bugs. These deserve more scrutiny even when they come from a single model.
-
-## Verdict Calibration
-
-A good verdict is useful, not comprehensive. The user should be able to read the "Act On" section, fix those issues, and ship with confidence. If your "Act On" list has more than 5 items, you're probably not filtering hard enough.
-
-The "Dismissed" section is not busywork. It's a trust mechanism. Showing the user what you rejected and why lets them override your judgment where they disagree. This is more valuable than hiding the rejected findings.

package/skills/pstack/interrogate/references/reviewer-prompt.md

@@ -1,72 +0,0 @@
-# Reviewer Prompt Template
-
-Build each reviewer subagent's prompt from this template, filling in the placeholders.
-
----
-
-You are an adversarial code reviewer. Find real problems in the code below: bugs, design flaws, security issues, and maintainability concerns. You are not here to be helpful or encouraging. You are here to stress-test.
-
-## Intent
-
-The author's stated intent for this change:
-
-> {INTENT}
-
-You are reviewing whether the code achieves this intent well. Do NOT question the intent itself. Assume the goal is correct and challenge the execution.
-
-## Code Under Review
-
-{DIFF_OR_FILES}
-
-## Review Rubric
-
-{RUBRIC_CONTENTS}
-
-## Code Quality Lens
-
-{CODE_QUALITY_CONTENTS}
-
-## Instructions
-
-Review the code through every lens in the rubric and the code-quality lens above that you find relevant. Do not force lenses that don't apply. A simple bug fix does not need paragraphs about architectural integrity.
-
-For each finding, provide:
-
-1. **Severity**: `critical` | `warning` | `nit`
-   - `critical`: Would cause bugs, data loss, security issues, or fundamentally broken behavior
-   - `warning`: Design concern, maintainability risk, or correctness issue that isn't immediately broken but will cause pain
-   - `nit`: Style, naming, minor improvement. Only include nits if they're genuinely useful, not to pad your review.
-2. **Finding**: What the problem is, in concrete terms. Reference specific lines/functions.
-3. **Evidence**: Why you believe this is a problem. Show your reasoning. Don't just assert.
-4. **Suggestion** (optional): What you'd do instead, if you have a concrete alternative. Skip this if you don't have a clear fix.
-
-## What Makes a Good Finding
-
-- It references specific code, not vague concerns ("this could be better")
-- It explains WHY something is a problem, not just THAT it is
-- It distinguishes between "this is broken" and "I would have done this differently"
-- It considers the stated intent. A finding that ignores the context of what's being built is a bad finding
-
-## What to Avoid
-
-- Restating what the code does without identifying a problem
-- Suggesting rewrites for working code because you'd prefer a different style
-- Raising hypothetical issues ("what if someone passes null here") without evidence that the code path is reachable
-- Praising the code. You're an adversary, not a cheerleader. If you find nothing wrong, say "no findings" and stop.
-
-## Output
-
-Return your findings as a structured list. If you have zero findings, say so. An empty review is a valid outcome.
-
-```
-## Findings
-
-### 1. [Severity] Short title
-**Location**: file:line or function name
-**Finding**: What's wrong
-**Evidence**: Why this matters
-**Suggestion**: (optional) What to do instead
-
-### 2. [Severity] Short title
-...
-```

package/skills/pstack/interrogate/references/rubric.md

@@ -1,77 +0,0 @@
-# Review Rubric
-
-Review through whichever lenses are relevant. Not every lens applies to every change. Use judgment.
-
-## Correctness
-
-Does the code actually do what the intent says it should?
-
-- Edge cases: empty inputs, nil/undefined, boundary values, concurrent access
-- Error handling: are errors caught, propagated, or silently swallowed?
-- Off-by-one, type coercion, integer overflow, string encoding
-- State management: race conditions, stale closures, dangling references
-- Does the happy path work? Does the sad path work?
-- Idempotency: what happens if this operation runs twice, or if a previous run crashed halfway? If the answer is "it depends on what state was left behind," there's a missing reconciliation step.
-- Concurrency: if multiple actors can touch the same mutable state (files, branches, shared data), is access serialized structurally (locks, sequential phases, exclusive ownership), or by conventions that won't hold?
-
-When you find a potential bug, trace the execution path. Don't just flag "this could be nil". Show the call chain that makes it nil.
-
-## Root Causes vs. Symptoms
-
-Is the code fixing the actual problem or papering over a symptom?
-
-Answering this often requires looking beyond the changed files. Read the surrounding code (callers, callees, type definitions, sibling modules) and understand the architecture the change lives in. Use the tools available to you (Read, Grep, Glob) to explore. Follow the call chain. Read the types. Understand why the code exists before judging whether the change addresses the right layer.
-
-- Guard clauses that mask a deeper invariant violation
-- Retry logic that hides a broken contract
-- Type casts that silence a modeling error
-- If you see a workaround, ask: why is the workaround needed? What would a proper fix look like?
-- A fix in module A that should really be a fix in module B's contract
-- Instructions where structure would be better: if the fix is a comment saying "don't do X" or a convention someone has to remember, ask whether it could instead be a type constraint, a lint rule, or a runtime check that makes the wrong thing impossible
-
-## Structural Integrity
-
-Does the code fit well into the system it's part of?
-
-- Boundary discipline: is validation at system boundaries, or scattered through business logic? Validate data once where it enters the system, then trust it internally.
-- Abstraction level: is the code mixing high-level orchestration with low-level detail?
-- Coupling: does this change introduce dependencies that will make future changes harder?
-- Data model fit: do the data structures match the actual access patterns? The right structure makes downstream code obvious; the wrong one fights you at every turn.
-- Bolted-on vs. integrated: was the change patched onto the existing design, or does it read as if the design always accounted for it? If the new requirement had been known from the start, would the code look like this?
-- Legacy dual-paths: does the change introduce a new API while keeping the old one alive? If there are no external consumers, migrate callers and delete the old path in the same wave. Don't leave compatibility layers that will become permanent.
-
-Don't penalize simple code for lacking abstraction. Premature abstraction is worse than duplication.
-
-## Verification
-
-Can you tell that this code works from reading it?
-
-- Are there tests? Do they test behavior or implementation details?
-- Are there assertions/invariants that would catch regressions?
-- If this is a bug fix: is there a test for the bug?
-- If this touches an integration boundary: is the full path tested?
-- Check the real thing, not a proxy: if the code checks liveness via file mtime or cached state instead of reading the actual value, that's a verification gap.
-- For delegated or async work: does the code verify actual output artifacts, or does it trust self-reports and summaries?
-
-## Complexity Budget
-
-Is the complexity justified by what the code accomplishes?
-
-- Code that could be simpler without losing correctness or clarity
-- Abstractions that serve only one call site
-- Configuration or parameterization for cases that don't exist yet
-- Dead code, unused imports, vestigial parameters
-- Over-engineering: "just in case" code paths with no current callers
-- Obsolete compatibility paths kept alive for transitional stability that's no longer needed. If the migration is done, delete the scaffolding
-- Does the user experience justify the complexity? Every feature, control, and option should earn its place. Half-finished features are worse than missing ones.
-
-Simpler is better unless simpler is wrong. Three lines of duplication beat a premature abstraction.
-
-## Security
-
-Only flag security issues you can actually trace through the code. "This could be an injection vector" without showing the input path is not useful.
-
-- User input flowing to dangerous sinks (SQL, shell, eval, innerHTML) without sanitization
-- Authentication/authorization gaps in new endpoints
-- Secrets in code, logs, or error messages
-- TOCTOU (time-of-check-time-of-use) in security-critical paths

package/skills/pstack/poteto-mode/references/plan.md

@@ -1,105 +0,0 @@
-# Plan
-
-Produce a phased implementation plan grounded in the **Principles** section of the `poteto-mode` skill. The plan is the deliverable. Do not implement.
-
-Open a todolist with one item per step below.
-
-## 0. Triage
-
-Skip the plan when the change is one or two files with an obvious approach. Say so and stop.
-
-Plan when the change spans three or more files, introduces architecture, has competing approaches or unclear scope, or the user asked for one.
-
-## 1. Re-read principles
-
-Read the **Principles** section of the `poteto-mode` skill end to end, and the leaf `principle-*` skills it indexes. The principles govern every plan decision; cross-link them.
-
-## 2. Scope and constraints
-
-State your read of scope and constraints in one paragraph. Use `AskQuestion` only for genuinely ambiguous intent (the **never-block-on-the-human** principle skill); give concrete options with each open question.
-
-Resolve what is in scope vs explicitly out, technical or platform constraints, patterns to preserve, and the definition of done.
-
-## 3. Explore in subagents
-
-Delegate codebase exploration (the **guard-the-context-window** principle skill).
-
-- Prefer `subagent_type: "poteto-agent"`. `generalPurpose` is the fallback. Never use the built-in `plan` subagent_type; it ignores this skill.
-- Pass `model:` explicitly per the configured roles (defaults `composer-2.5-fast` for code, `claude-opus-4-8-thinking-xhigh` for judgment).
-
-Each explorer returns file pointers, conventions, dependencies, test infrastructure, and entry points. No inlined dumps.
-
-## 4. Write the plan
-
-The user specifies where the plan lives.
-
-Single file `NN-slug.md` for small plans. For three or more phases, a directory with `overview.md` plus phase files:
-
-```
-NN-slug/
-├── overview.md
-├── phase-1-scaffold.md
-├── phase-2-...md
-└── testing.md
-```
-
-### Phase sizing
-
-- One function or type plus tests, or one bug fix. Not "one file".
-- Two to three files touched, max.
-- Prefer eight to ten small phases over three to four large ones to preserve option value (the **foundational-thinking** principle skill).
-- Split if a phase has more than five test cases or three functions.
-
-### Overview file
-
-- **Context.** Problem and why now.
-- **Scope.** Included; explicitly excluded.
-- **Constraints.** Technical, platform, dependency, pattern.
-- **Alternatives.** Two or three approaches sketched, choice and rationale (the **exhaust-the-design-space** principle skill). Skip when constraints dictate one.
-- **Applicable skills.** Domain skills the implementer should invoke, by name.
-- **Phases.** Ordered standard-markdown links to phase files.
-- **Verification.** Project-level commands.
-- **Implementation guidance.** Per section 6.
-
-### Phase files
-
-- Back-link to overview.
-- **Goal.** What the phase accomplishes.
-- **Changes.** Files affected and the change at a high level. What and why, not how. No code snippets.
-- **Data structures.** Name the key types or schemas. One-line sketch only (the **foundational-thinking** principle skill).
-- **Verification.** Per section 6.
-
-Order phases so infrastructure and shared types land first (the **foundational-thinking** principle skill). Each phase should be independently shippable.
-
-For changes touching existing code, apply the **redesign-from-first-principles** principle skill: if we'd built this with the new requirement on day one, what would it look like? Redesign holistically; deliver incrementally.
-
-If a phase creates or edits a skill, the phase instructs the implementer to use the **create-skill** skill (Cursor's built-in for authoring SKILL.md files).
-
-## 5. Verification per phase
-
-Each phase needs both:
-
-**Static.** Type check, lint, project tests pass.
-
-**Runtime.** Exercise the feature on the matching surface via the relevant control skill:
-
-- Browser / Electron / Web UIs: the `control-ui` skill from the `cursor-team-kit` plugin.
-- CLIs and TUIs: the `control-cli` skill from the `cursor-team-kit` plugin.
-- Native mobile: whatever simulator-driving skill your team has.
-- No control skill for the touched surface: flag it in the plan.
-
-For bug fixes, the loop is reproduce on the surface, fix, verify on the same surface. Unit tests show a branch behaves a certain way; they do not prove the bug is gone (the **prove-it-works** principle skill).
-
-## 6. Implementation guidance
-
-In the overview, name which poteto-mode non-negotiables the implementer must apply, by name:
-
-- the **how** skill over each unfamiliar subsystem before changing it.
-- the **interrogate** skill for adversarial review on contested designs before shipping.
-- `/deslop` over each diff before commit. the **unslop** skill over any prose surface.
-- the **show-me-your-work** skill to keep a decision trail when the plan is large enough to need an auditable record.
-- Cursor's built-in **babysit** skill after opening the PR.
-
-## 7. Hand back
-
-Summarize phases, scope boundaries, applicable skills, and verification. Stop. The user decides when implementation starts.