@mccune1224/pi-pstack 0.1.0 → 0.2.0

package/skills/why/references/investigator-prompt.md

@@ -1,6 +1,6 @@
 # Investigator Prompt Template
 
-Build each investigator's prompt from this template; fill in the placeholders. Append the single category playbook `sources/<source>.md` matching this investigator's evidence category (see `source-playbook.md` for the index). If the target code looks defensive (null checks, retry logic, timeout handling, rate limiting, feature flags, egress guards, OOM handlers), also append `sources/incident-postmortem.md` for the incident-flavored queries to run inside its own source.
+Build each investigator's prompt from this template. Fill in the placeholders. Append the single category playbook `sources/<source>.md` matching this investigator's evidence category (see `source-playbook.md` for the index). If the target code looks defensive (null checks, retry logic, timeout handling, rate limiting, feature flags, egress guards, OOM handlers), also append `sources/incident-postmortem.md` for the incident-flavored queries to run inside its own source.
 
 ---
 
@@ -10,7 +10,7 @@ Other investigators search different sources in parallel. Don't try to cover eve
 
 ## Operating Posture
 
-Work like a careful, cautious, precise investigator. Don't produce a narrative; surface evidence and describe it accurately, including the parts that don't fit a tidy story. The more boring and exact your output, the more useful it is. A single verbatim quote with a precise citation beats a paragraph of plausible-sounding summary.
+Work like a careful, cautious, precise investigator. Don't produce a narrative. Surface evidence and describe it accurately, including the parts that don't fit a tidy story. The more boring and exact your output, the more useful it is. A single verbatim quote with a precise citation beats a paragraph of plausible-sounding summary.
 
 - **Quote, don't paraphrase** when the exact wording matters. Citations should let the reader jump to the source and confirm the claim in seconds.
 - **Go wide before going deep.** Cast a broad first net so you don't miss related context. Only then narrow in.
@@ -44,16 +44,16 @@ Work like a careful, cautious, precise investigator. Don't produce a narrative;
 
 ## Investigation Instructions
 
-Gather **evidence**; don't answer the question directly. The synthesizer weighs the evidence and forms conclusions. Follow this loop:
+Gather **evidence**. Don't answer the question directly. The synthesizer weighs the evidence and forms conclusions. Follow this loop:
 
 1. **Cast a wide net first.** Start broad so you don't miss related context, then narrow in on specific items.
 2. **Read the whole thing.** Read any PR, ticket, doc, or thread fully, not just the title or summary. The key evidence is often buried in a comment, a subtask, or a follow-up.
-3. **Follow links within your assigned source.** If a PR references another PR or commit, pull it. If a ticket links a parent or sibling, pull it. If a doc links another doc, pull it. Stay inside your assigned source. When you spot a cross-source reference, do NOT chase it yourself. Record it under "Additional Leads" so the investigator assigned to that source can pick it up. The one-investigator-per-category design depends on this; chasing cross-source links duplicates work and confuses scope.
+3. **Follow links within your assigned source.** If a PR references another PR or commit, pull it. If a ticket links a parent or sibling, pull it. If a doc links another doc, pull it. Stay inside your assigned source. When you spot a cross-source reference, do NOT chase it yourself. Record it under "Additional Leads" so the investigator assigned to that source can pick it up. The one-investigator-per-category design depends on this. Chasing cross-source links duplicates work and confuses scope.
 4. **Capture quotes verbatim** with their location (PR number, ticket ID, URL, commit hash, file:line). The synthesizer needs to cite this precisely.
 5. **Note absences.** If you searched for something and came up empty, that's also a finding. Record what you searched for and what you didn't find.
 6. **Watch for contradictions.** If two items in your source disagree, record both. Don't suppress the inconvenient one.
 
-Don't synthesize or form a final opinion on "the why." Collect the raw material honestly and completely; the synthesizer does the reasoning.
+Don't synthesize or form a final opinion on "the why." Collect the raw material honestly and completely. The synthesizer does the reasoning.
 
 ## Epistemic Discipline
 

package/skills/why/references/source-playbook.md

@@ -1,6 +1,6 @@
 # Source playbooks
 
-The why skill spawns one investigator per available evidence category, each reading a single source-specific playbook below. The playbooks are concrete examples for common MCPs; adapt them for a different MCP in the same category.
+The why skill spawns one investigator per available evidence category, each reading a single source-specific playbook below. The playbooks are concrete examples for common MCPs. Adapt them for a different MCP in the same category.
 
 | Category | Playbook | Example MCP it documents |
 |---|---|---|

package/skills/why/references/sources/databricks.md

@@ -2,20 +2,20 @@
 
 ## What this source contains
 
-Databricks is the product-analytics, data-pipeline, and warehouse-telemetry layer. It complements Datadog: Datadog is the *infra/runtime* view, Databricks is the *product/data* view (what users did, which experiments ran, how feature usage evolved, where a threshold constant came from).
+Databricks is the product-analytics, data-pipeline, and warehouse-telemetry layer. It complements Datadog. Datadog is the *infra/runtime* view, Databricks is the *product/data* view (what users did, which experiments ran, how feature usage evolved, where a threshold constant came from).
 
 - **Product analytics events.** `your_warehouse.events.analytics_track_event` (raw) and typed, deduplicated per-event dbt models in `<your_analytics_db>.<schema>.<table>`. User behavior: feature invocations, clicks, accepts/rejects, submissions, client-reported errors.
-- **Usage & billing events.** `your_warehouse.events.usage_event` / `<your_analytics_db>.<schema>.stg_usage_events`; `your_warehouse.events.raw_model_event` / `<your_analytics_db>.<schema>.stg_raw_model_events`. For cost- or volume-driven decisions.
+- **Usage & billing events.** `your_warehouse.events.usage_event` / `<your_analytics_db>.<schema>.stg_usage_events`, `your_warehouse.events.raw_model_event` / `<your_analytics_db>.<schema>.stg_raw_model_events`. For cost- or volume-driven decisions.
 - **Experiment / feature-flag data.** Exposure and outcome tables. **Schema is company-specific.** Probe with `SHOW TABLES` before assuming names.
 - **System tables.** `system.query.history`, `system.compute.warehouses`, `system.billing.*`, `system.access.audit`. Answer "was this query expensive?", "how often did anyone run this?", "when did warehouse load spike?"
-- **dbt lineage.** Models in `<your_analytics_db>.<schema>` reveal what pipelines depend on a table/field; upstream changes frequently motivate consumer-code changes.
+- **dbt lineage.** Models in `<your_analytics_db>.<schema>` reveal what pipelines depend on a table/field. Upstream changes frequently motivate consumer-code changes.
 - **Databricks notebooks.** Exploratory analyses engineers wrote before code changes. **Not queryable via the SQL MCP.** If you suspect the rationale lives in a notebook, name it as a gap.
 
 ## How to search it
 
 Use the Databricks SQL MCP. Primary tool: `execute_sql_read_only`. If it returns a `statement_id`, poll with `poll_sql_result` rather than re-running.
 
-**Orient before querying.** Schemas are company-specific; probe before trusting a table name:
+**Orient before querying.** Schemas are company-specific. Probe before trusting a table name:
 
 ```sql
 SHOW TABLES IN <your_analytics_db>.<schema> LIKE '*<keyword>*';
@@ -24,7 +24,7 @@ DESCRIBE TABLE <your_analytics_db>.<schema>.stg_<event>;
 
 **Time-bound every query.** These tables are huge and unconstrained scans time out. Filter on `_timestamp` (events) or `start_time` (`system.query.history`) with a window bracketing the ship date, typically ~30 days before and after, wider only for strong reason.
 
-**Prefer typed dbt models over the raw table.** `<your_analytics_db>.<schema>.<table>` is deduplicated, typed, and liquid-clustered; `your_warehouse.events.analytics_track_event` has duplicates and untyped `properties_json`. Model-name pattern: `stg_<source>_<event_name_with_underscores>`, where `<source>` is `app`, `backend`, `website`, or `cli`; confirm the exact model name with `SHOW TABLES` when the pattern alone doesn't resolve it. Drop to the raw table only when there's no dbt model yet, or you need events from inside the dbt refresh lag.
+**Prefer typed dbt models over the raw table.** `<your_analytics_db>.<schema>.<table>` is deduplicated, typed, and liquid-clustered. `your_warehouse.events.analytics_track_event` has duplicates and untyped `properties_json`. Model-name pattern: `stg_<source>_<event_name_with_underscores>`, where `<source>` is `app`, `backend`, `website`, or `cli`. Confirm the exact model name with `SHOW TABLES` when the pattern alone doesn't resolve it. Drop to the raw table only when there's no dbt model yet, or you need events from inside the dbt refresh lag.
 
 **Column conventions on the typed dbt models** (knowing these avoids a `DESCRIBE` round-trip):
 
@@ -53,7 +53,7 @@ Beyond the pattern shapes above:
 
 - **Instrumented ≠ caused.** An event's existence means someone cared enough to log it, not that the target code exists *because* of it. Pair with a PR/commit citation from the git investigator before claiming causation.
 - **Silent instrumentation changes.** A step function in event volume may mean a new event started being logged, not that user behavior changed. Check for instrumentation PRs in the same window before reading the ramp as a feature-launch signal.
-- **Schema drift.** Event properties evolve; a column on the typed dbt model today may not have existed when the target was written. Older data may carry the property only inside raw `properties_json`.
+- **Schema drift.** Event properties evolve. A column on the typed dbt model today may not have existed when the target was written. Older data may carry the property only inside raw `properties_json`.
 - **dbt refresh lag.** `<your_analytics_db>.<schema>.*` is rebuilt on a schedule (often hourly/daily). For events from the last few hours, fall back to `your_warehouse.events.*` and deduplicate by `_id`.
 - **Company-specific tables.** Experiment, feature-flag, billing, and usage tables vary. Reporting a result from a table whose existence you never confirmed is a classic failure mode. Probe with `SHOW TABLES` / `DESCRIBE TABLE` first.
 - **Retention cliff.** If the relevant window predates the table's retention or the dbt model's creation date, that's a *gap*, not a null result. Name it explicitly so the synthesizer doesn't read "no results" as "no activity."
@@ -66,5 +66,5 @@ For each relevant finding:
 - Fully-qualified table name and the exact query you ran
 - Time window queried
 - Compact numeric summary (counts, percentiles, first/last-seen timestamps). **Don't dump raw rows.**
-- Temporal correlation with the target's ship date (e.g., "first row 2024-08-15; PR #49074 merged 2024-08-14")
+- Temporal correlation with the target's ship date (e.g., "first row 2024-08-15, PR #49074 merged 2024-08-14")
 - Relevance + strength: direct / circumstantial / weak

package/skills/why/references/sources/datadog.md

@@ -2,15 +2,15 @@
 
 ## What this source contains
 
-Datadog holds the runtime record: what actually happened in production, as opposed to what was planned or discussed.
+Datadog holds the runtime record, what actually happened in production, as opposed to what was planned or discussed.
 
-- **Metrics.** Counters, gauges, histograms instrumented by the team. A metric's *presence* is itself evidence: someone thought this number worth watching.
+- **Metrics.** Counters, gauges, histograms instrumented by the team. A metric's *presence* is itself evidence. Someone thought this number worth watching.
 - **Monitors & alerts.** Conditions the team decided warranted waking someone up. A monitor firing on `rate_limit_hit > 10/min` is direct evidence the team worried about that threshold.
 - **Dashboards.** Curated views. The charts tell you what the team considers important for a subsystem.
 - **APM traces & spans.** Request-level runtime data. Useful for "why is this slow" / "why is there a timeout here" questions.
 - **Logs.** High-volume event records. Often contain the error conditions that motivated defensive code.
 - **Incidents.** Formal incident records with timelines and linked postmortems.
-- **Notebooks.** Exploratory investigations; often contain hypotheses and analyses.
+- **Notebooks.** Exploratory investigations. Often contain hypotheses and analyses.
 
 Datadog answers "what was the production reality around the time this code was written?", which often explains the code's shape.
 
@@ -51,7 +51,7 @@ Use the Datadog MCP. Start broad, then narrow.
    analyze_datadog_logs (SQL-style aggregations, only when you need counts)
    ```
 
-   Search with symbols, error strings, or feature names. **Strongly prefer time-bounded queries** (e.g., 30 days before/after the change). Log volume is huge; unconstrained searches waste time and may time out.
+   Search with symbols, error strings, or feature names. **Strongly prefer time-bounded queries** (e.g., 30 days before/after the change). Log volume is huge. Unconstrained searches waste time and may time out.
 
 5. **APM spans and traces.**
 
@@ -74,7 +74,7 @@ Use the Datadog MCP. Start broad, then narrow.
 
 ## What good evidence looks like here
 
-- A monitor whose query and threshold match the constraint the code enforces (code clamps to 100; monitor alerts when requests exceed 100/min)
+- A monitor whose query and threshold match the constraint the code enforces (code clamps to 100, monitor alerts when requests exceed 100/min)
 - A dashboard created by the target's author, with widgets that correspond to what the code measures or guards against
 - A metric showing a production spike immediately before the code was merged, and stable values after
 - An incident record referencing the target code, the same symbols, or the same error strings

package/skills/why/references/sources/incident-postmortem.md

@@ -6,8 +6,8 @@ Not a separate source, a **cross-cutting angle**. Incidents often motivate defen
 - **Linear**: look for tickets labeled `incident`, `sev-*`, `postmortem-action-item`, `reliability`
 - **Slack**: search `#sev-*` and `#incident-*` channels around the dates the target code was added
 - **Git**: commits with messages like "fix for incident", "add defensive check", "revert" followed by "re-apply with..." are strong signals
-- **Datadog**: `search_datadog_incidents` for formal incident records with timelines; dashboards and monitors created as postmortem action items
-- **Sentry**: issues whose first-seen/last-seen window aligns with the target's PR ship date; stack traces through the target
+- **Datadog**: `search_datadog_incidents` for formal incident records with timelines, dashboards and monitors created as postmortem action items
+- **Sentry**: issues whose first-seen/last-seen window aligns with the target's PR ship date, stack traces through the target
 - **Databricks**: product-analytics events that classify an error condition (client-reported failures, user-visible retry events, etc.) often spike during an incident window. A drop in that event count after the target PR ships is circumstantial support that the target code resolved the user-visible symptom, even when Datadog/Sentry signal is noisy.
 
 If you find an incident link, fetch the full postmortem. Postmortems typically have an "Action Items" section that ties directly to code changes. When multiple sources corroborate (a Datadog incident ID appears in a Linear ticket, which appears in a Notion postmortem, which appears in a Slack thread that links to the target PR, and the Databricks error-event count drops after the fix), the evidence is especially strong.

package/skills/why/references/sources/linear.md

@@ -18,7 +18,7 @@ Use the Linear MCP.
 
 1. **Start with linked tickets.** If the seed commits or PRs reference ticket IDs (e.g., `ENG-1234`, `[BUG-567]`), fetch those first with `get_issue`. Read the full issue including comments.
 2. **List related issues by keyword.** Use `list_issues` with text search for the feature name, key symbol, or business term. Try multiple phrasings.
-3. **Walk the issue tree.** If you land on a sub-issue, fetch its parent. Sub-issues are tactical; parents often carry the "why."
+3. **Walk the issue tree.** If you land on a sub-issue, fetch its parent. Sub-issues are tactical. Parents often carry the "why."
 4. **Read project docs.** If the issue belongs to a project, use `get_project` and check attached docs. Project-level documents are where specs and rationale are most often captured.
 5. **Check labels and milestones.** Labels hint at the category of motivation (customer-request, incident-followup, compliance). Milestones tie work to deadlines, which often reveal motivation.
 
@@ -42,7 +42,7 @@ Use the Linear MCP.
 
 For each relevant ticket:
 - Ticket ID and title
-- The problem/motivation quoted from the description or comments (not paraphrased; the synthesizer needs the exact text to cite)
+- The problem/motivation quoted from the description or comments (not paraphrased. The synthesizer needs the exact text to cite)
 - Labels, parent issue, project
 - Author, created date, closed date
 - Link to the ticket if available

package/skills/why/references/sources/notion.md

@@ -23,7 +23,7 @@ Use the Notion MCP.
    - Author handles (design docs are often authored before the code lands)
    - Error strings or user-visible terms
    - Time-bounded queries if you know when the code shipped
-2. **Fetch candidate pages with `notion-fetch`.** Read the full content, not the preview; rationale is often buried mid-document.
+2. **Fetch candidate pages with `notion-fetch`.** Read the full content, not the preview. Rationale is often buried mid-document.
 3. **Follow backlinks and child pages.** Design docs often have sub-pages for alternatives considered, appendices, or implementation notes.
 4. **Check related databases.** `notion-query-data-sources` and `notion-query-meeting-notes` can surface meeting notes that discussed the decision.
 5. **Search author-specific spaces.** If the PR author has a personal notebook (common at some companies), it may hold exploratory thinking that preceded the code.
@@ -38,8 +38,8 @@ Use the Notion MCP.
 
 ## Common pitfalls
 
-- **Outdated docs.** Specs are often written before implementation and not updated; the doc may describe a plan that changed. Cross-check against the actual PR.
-- **Doc vs. reality drift.** A spec may say "we'll do X" but the code actually does Y. Flag the divergence; the synthesizer will surface the contradiction.
+- **Outdated docs.** Specs are often written before implementation and not updated. The doc may describe a plan that changed. Cross-check against the actual PR.
+- **Doc vs. reality drift.** A spec may say "we'll do X" but the code actually does Y. Flag the divergence. The synthesizer will surface the contradiction.
 - **Boilerplate templates.** Some orgs require a "Why" section that gets filled with fluff. Look for specificity.
 - **Unlinked docs.** The most relevant doc may not be linked from anywhere. Broad keyword searches help.
 - **Multiple drafts.** If a topic has multiple docs, find the one that was finalized or most recently updated. Check dates.

package/skills/why/references/sources/sentry.md

@@ -8,7 +8,7 @@ Sentry is the archive of things that went wrong. For defensive, corrective, or e
 - **Events.** Individual error instances within an issue (stack traces, tags, user context)
 - **Releases.** Deployment records with associated issues (useful for "which version fixed this?")
 - **Replays.** Session recordings of user-facing errors (if enabled)
-- **Profiles.** Performance profiling data (less useful for "why"; more for "how slow")
+- **Profiles.** Performance profiling data (less useful for "why", more for "how slow")
 - **Issue comments & assignments.** Sometimes contain engineer notes on root cause
 
 The most valuable thing Sentry provides is **temporal correlation**: "issue X was created 2024-01-02, peaked at 500 events/day, stopped appearing after release v2.14.0 on 2024-01-15, the release that shipped the defensive check."
@@ -67,7 +67,7 @@ Use the Sentry MCP.
    analyze_issue_with_seer
    ```
 
-   Seer produces AI root-cause analyses. Useful as a hypothesis generator, but treat them as inference, not authoritative. The actual events and stack traces are the primary evidence; Seer's narrative is secondary.
+   Seer produces AI root-cause analyses. Useful as a hypothesis generator, but treat them as inference, not authoritative. The actual events and stack traces are the primary evidence. Seer's narrative is secondary.
 
 ## What good evidence looks like here
 
@@ -80,8 +80,8 @@ Use the Sentry MCP.
 ## Common pitfalls
 
 - **Grouping drift.** Sentry groups errors by fingerprint. Refactors or renames can track the "same" error under a new issue ID. If an issue ends abruptly, the error may have just been regrouped. Check for new issues immediately after.
-- **Release correlation is noisy.** A release contains many commits. An issue stopping at v2.14.0 doesn't prove the target fixed it; another change in the same release might have. Cross-reference with the target's exact commit.
-- **Silent fixes.** Sometimes the error stops because upstream changed, not because of the defensive code. The correlation suggests the fix; it doesn't prove authorship.
+- **Release correlation is noisy.** A release contains many commits. An issue stopping at v2.14.0 doesn't prove the target fixed it. Another change in the same release might have. Cross-reference with the target's exact commit.
+- **Silent fixes.** Sometimes the error stops because upstream changed, not because of the defensive code. The correlation suggests the fix. It doesn't prove authorship.
 - **Resolved != fixed.** Issues can be marked "resolved" manually without any code change. Treat `resolved` as a human marker, not evidence that code fixed it.
 - **Seer hallucinations.** Seer can generate confident-sounding explanations that aren't right. Fall back to the actual events, stack traces, and timestamps when making claims.
 - **Sampling.** Some projects sample events aggressively. A low event count may just mean high sampling, not a rare error. If in doubt, note the gap.

package/skills/why/references/sources/slack.md

@@ -9,7 +9,7 @@
 - Post-merge discussions that explain why something was revisited
 - DMs (usually not searchable, scope accordingly)
 
-Slack is frequently where the *real* decisions got made, especially for smaller changes that didn't warrant a doc. It's also the most ephemeral source: threads get deleted, channels get archived, and search quality degrades over time.
+Slack is frequently where the *real* decisions got made, especially for smaller changes that didn't warrant a doc. It's also the most ephemeral source. Threads get deleted, channels get archived, and search quality degrades over time.
 
 ## How to search it
 
@@ -38,7 +38,7 @@ Slack MCP tools vary. Check which Slack MCP is available and inspect its tool sc
 ## Common pitfalls
 
 - **Channel archaeology limits.** Very old messages may be gone due to retention policies. If you can't find anything before a certain date, note the retention cliff.
-- **Unsearched DMs.** Many decisions happen in DMs that aren't searchable. You'll miss them; that's a known limitation.
+- **Unsearched DMs.** Many decisions happen in DMs that aren't searchable. You'll miss them. That's a known limitation.
 - **Speculative jokes as "decisions."** Slack is casual. "Lol just do the thing" isn't a decision, even if it preceded the commit. Look for considered discussion.
 - **Context collapse in single messages.** Without the thread, a single message often reads differently than in context. Always fetch threads.
 - **Auth failures.** If the MCP isn't authenticated, stop. Don't make up findings. Report that Slack wasn't searchable.

package/skills/why/references/synthesizer-prompt.md

@@ -1,6 +1,6 @@
 # Synthesizer Prompt Template
 
-Build the synthesizer's prompt from this template; fill in the placeholders.
+Build the synthesizer's prompt from this template. Fill in the placeholders.
 
 ---
 
@@ -41,7 +41,7 @@ You MUST follow the framework in `references/epistemics.md`. Read it in full bef
 2. **Reconcile overlapping findings.** Multiple investigators may have cited the same PR, ticket, or doc. Merge into a single, authoritative reference.
 3. **Identify contradictions.** If two items of evidence disagree, don't pick one. Surface both.
 4. **Calibrate confidence.** For each claim, identify the evidence and the tier. State Direct claims plainly with a citation. Hedge Inferred claims and explain the inference. Mark Speculative claims explicitly. Put claims with no evidence in the gaps section.
-5. **Verify citations by spot-checking.** You can read the codebase and call MCP tools to verify citations; do not write files, commit, or modify external state. If you're uncertain a cited item exists or says what's claimed, check it. Don't propagate errors.
+5. **Verify citations by spot-checking.** You can read the codebase and call MCP tools to verify citations. Do not write files, commit, or modify external state. If you're uncertain a cited item exists or says what's claimed, check it. Don't propagate errors.
 6. **Don't overreach.** The user will act on your output. Better to leave an open question open than to fill it with a confident-sounding guess.
 
 ## Output Format
@@ -121,7 +121,7 @@ One or two sentences summarizing your overall confidence. E.g.:
 Before finalizing, review your output against this checklist:
 
 1. Does every claim in "What We Found" have a citation? If not, add one or move the claim to "Inferred" or "Hypotheses."
-2. Is the phrasing tier-appropriate? (Direct claims can use "because"; Inferred claims cannot.)
+2. Is the phrasing tier-appropriate? (Direct claims can use "because". Inferred claims cannot.)
 3. Did you surface any contradictions you noticed, or did you quietly pick one?
 4. Does the "What We Don't Know" section exist and name specific gaps? If it's empty or missing, be suspicious. Historical investigations almost always have gaps.
 5. If the user embedded a hypothesis in their question, did you check it against the evidence rather than rubber-stamping it?

package/skills/how/references/critic-prompt.md

@@ -1,59 +0,0 @@
-# Critic Prompt Template
-
-Build each critic subagent's prompt from this template. Fill in the placeholders.
-
----
-
-You are reviewing the architecture of a codebase subsystem. An explanation of how it works has already been written. Read it to orient yourself, then read the actual code to form your own judgment.
-
-## Architectural Explanation
-
-{EXPLANATION}
-
-## Relevant Files
-
-{FILE_PATHS}
-
-## Critique Rubric
-
-{CRITIQUE_RUBRIC_CONTENTS}
-
-## Instructions
-
-Read the files listed above. Use the explanation as a map, but form your own opinions from the code itself. The explanation might miss things or frame them charitably.
-
-Find architectural problems, not line-level bugs or style issues. Ask whether this subsystem is built well for what it needs to do and how it will need to evolve.
-
-For each finding:
-
-1. **Severity**: `structural` | `concern` | `observation`
-   - `structural`: a fundamental architectural problem. Wrong abstraction boundary, broken data model, coupling that will block future work
-   - `concern`: a real issue that makes the system harder to work with or reason about, but not fundamentally broken
-   - `observation`: worth noting. A tradeoff that might not age well, a pattern inconsistent with the rest of the codebase, technical debt
-2. **Finding**: the architectural issue. Be specific. Name the components, the boundary, the coupling.
-3. **Evidence**: concrete code that demonstrates the problem. Don't just assert that "this is too coupled". Show the dependency chain.
-4. **Impact**: what the issue costs. Harder to test? Harder to change? Performance cliff at scale? Be concrete about the consequence.
-
-## What to Avoid
-
-- Line-level code review (not your job here)
-- Suggesting rewrites without demonstrating a problem with the current approach
-- "This could use more abstraction" without showing what the abstraction would actually solve
-- Flagging intentional tradeoffs with clear benefits as issues
-
-If the architecture is sound, say so. An empty critique is a valid outcome.
-
-## Output
-
-```
-## Findings
-
-### 1. [Severity] Short title
-**Components**: Which parts of the system are involved
-**Finding**: What's wrong architecturally
-**Evidence**: Concrete code references
-**Impact**: What this costs in practice
-
-### 2. [Severity] Short title
-...
-```

package/skills/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.