minsky

Before asserting a causal or mechanism claim about tool/system behavior, OR a factual claim about what a CURRENT artifact (spec/doc/config/rule) says, requires, or contradicts, OR changing behavior to conform to a remembered criterion, OR a casual claim about what a task/artifact IS/DOES/its status/scope — list the factual premises the claim rests on, identify the cheapest falsifier first, and check it (read the installed source / query the system's own record / re-read the live, AUTHORITATIVE artifact — not a stale local cache) before asserting or acting. Use when about to explain WHY something happened, WHAT a tool will do, WHAT a spec/doc says or requires, or WHAT a task/artifact is/does/its status is, based on an assumed or remembered claim.

Before asserting a causal or mechanism claim about tool/system behavior, OR a factual claim about what a CURRENT artifact (spec/doc/config/rule) says, requires, or contradicts, OR changing behavior to conform to a remembered criterion, OR a casual claim about what a task/artifact IS/DOES/its status/scope — list the factual premises the claim rests on, identify the cheapest falsifier first, and check it (read the installed source / query the system's own record / re-read the live, AUTHORITATIVE artifact — not a stale local cache) before asserting or acting. Use when about to explain WHY something happened, WHAT a tool will do, WHAT a spec/doc says or requires, or WHAT a task/artifact is/does/its status is, based on an assumed or remembered claim.

Review hook-calibration JSONL logs and, for any log past its review threshold, false-positive-classify the matched records and emit ONE operator-routed Ask with the FP rate plus a flip/tune/keep recommendation — then advance the watermark. Use when running the periodic calibration sweep (scheduled or manual), or when asked to "review the calibration data" for the causal-premise / retrospective-trigger detector hooks.

Review hook-calibration JSONL logs and, for any log past its review threshold, false-positive-classify the matched records and emit ONE operator-routed Ask with the FP rate plus a flip/tune/keep recommendation — then advance the watermark. Use when running the periodic calibration sweep (scheduled or manual), or when asked to "review the calibration data" for the causal-premise / retrospective-trigger detector hooks.

Full implementation lifecycle for a Minsky task: read spec, plan, code, test, verify, commit, create PR, and drive to merge. All work happens in session workspaces with absolute paths. Use when implementing a task, starting development, or beginning work in a session.

Writing engineering essays, position papers, technical blog posts, and architecture memos intended for external or semi-external readers. Use when drafting or revising long-form argumentative prose — Notion position papers, public blog posts, shared design docs meant to persuade, RFCs with argumentative structure. Provides structural patterns (lead with position, justify after), section-heading heuristics (sentence case, specific, opinionated), an AI-voice-tells checklist (cadence uniformity, reveal- signposting, contrast sentences and rule of three, vocabulary, heading patterns), and a revision workflow. Skip for task specs (use create-task), rule files (use create-rule), code comments, or short internal-only docs.

Writing engineering essays, position papers, technical blog posts, and architecture memos intended for external or semi-external readers. Use when drafting or revising long-form argumentative prose — Notion position papers, public blog posts, shared design docs meant to persuade, RFCs with argumentative structure. Provides structural patterns (lead with position, justify after), section-heading heuristics (sentence case, specific, opinionated), an AI-voice-tells checklist (cadence uniformity, reveal- signposting, contrast sentences and rule of three, vocabulary, heading patterns), and a revision workflow. Skip for task specs (use create-task), rule files (use create-rule), code comments, or short internal-only docs.

Main-agent skill for coordinating the merge of a PR after the canonical `minsky-reviewer[bot]` review. Covers: gathering bot review status, running the local smoke test, reading posted review prose before retriggering, diagnosing reviewer-bot silence, and bypass-merging bot-authored PRs.

Create a new task with a properly structured spec. Takes task intent and generates a spec with required sections (Summary, Success Criteria, Scope, Acceptance Tests, Context) before calling tasks_create.

Create a new task with a properly structured spec. Takes task intent and generates a spec with required sections (Summary, Success Criteria, Scope, Acceptance Tests, Context) before calling tasks_create.

Prepare and create a pull request: verify completeness, generate description, format title, and submit via MCP tools. Use when creating a PR, preparing a PR, or submitting changes for review.

Prepare and create a pull request: verify completeness, generate description, format title, and submit via MCP tools. Use when creating a PR, preparing a PR, or submitting changes for review.

Draft a Minsky ADR (Architecture Decision Record) using the Michael-Nygard format with sequential numbering in docs/architecture/adr-NNN-<slug>.md. Use when committing to one architectural choice among alternatives where future readers will ask "why this and not that?" — single decisions, not multi-phase proposals.

Draft a Minsky RFC end-to-end: scope check, research pass, write, dispatch expert-review subagent, revise, publish to Notion under the Minsky home with RFC: prefix and Draft status. Use when proposing a new subsystem, a multi-phase roadmap, a cross-cutting architectural move, or any strategic direction that benefits from a defensible written argument.

Draft a Minsky ADR (Architecture Decision Record) using the Michael-Nygard format with sequential numbering in docs/architecture/adr-NNN-<slug>.md. Use when committing to one architectural choice among alternatives where future readers will ask "why this and not that?" — single decisions, not multi-phase proposals.

Draft a Minsky RFC end-to-end: scope check, research pass, write, dispatch expert-review subagent, revise, publish to Notion under the Minsky home with RFC: prefix and Draft status. Use when proposing a new subsystem, a multi-phase roadmap, a cross-cutting architectural move, or any strategic direction that benefits from a defensible written argument.

Develop, test, and ship the cockpit-tray Tauri macOS menu-bar app (cockpit-tray/**) — the native shell that supervises the cockpit daemon and hosts the in-app cockpit window (sibling to cockpit-design, which owns the web UI). Encodes the two-layer mental model (cockpit-web changes auto-rebuild via the tray's watchers, mt#2297/mt#2299; the tray's own Rust binary does NOT and needs `bun run dev` or a rebuild+reinstall), the `tauri dev` iteration loop, why a merged change is not in the running menu bar, the release-install path, auto-update (tauri-plugin-updater, mt#2201), the testing tiers (mt#2226, including that `cargo check` does not verify GUI behavior), and Tauri gotchas (external-URL webviews lose IPC, dock suppression, standalone package, supervisor model ADR-014/mt#2241). Use when working in cockpit-tray/**, testing a tray change, asking 'why don't I see my change in the menu bar', or building the harness-host ladder (mt#2230).

Set DONE on the bypass-merge fallback path: confirm the PR is merged AND the merge-commit body contains the canonical bypass-merge audit-trail signature, then transition IN-REVIEW → DONE. The reviewer bot (`minsky-reviewer[bot]`) does the verification work at review time; this skill only confirms the closeout signal. Use when: "verify mt#X", "check mt#X is done", "close out mt#X", "audit mt#X".

Drive a task through PLANNING to READY: investigate the spec, surface gaps, file subtasks, and run the gate check. Use when: 'investigate mt#X', 'plan mt#X', 'look into mt#X', "what's the gap for mt#X", 'bring mt#X to ready', 'research mt#X', 'analyze mt#X spec'. Does NOT create new tasks (use /create-task) and does NOT implement (use /implement-task).

Minsky-domain patterns for Cockpit UI work: entity model (tasks/sessions/changesets/PRs/asks/agents) and their conventions, mission-control density patterns, command-palette UX, drill-down navigation, dark-mode elevation, attention-debt visualization, workstream display. Use when designing or rebuilding Cockpit widgets (src/cockpit/web/**), implementing entity displays, or auditing Cockpit UI against Minsky-domain conventions. Complements the 12 vendored Tier-1 skills (visual design / engineering / IA) with the Minsky-specific layer those skills don't cover.

Structured post-failure analysis that identifies root causes and produces durable fixes to process artifacts. Auto-triggers on user-side correction signals ("that's wrong", "you keep doing this", "why did you do that?") AND on agent self-recognized failure signals ("I owe you an apology", "I was wrong about X", "I should have caught this", "I anchored on X and missed Y", "I didn't think it through") — match by meaning, not literal string. Use when a post-merge audit finds issues, the same feedback is given repeatedly, a subagent produces incomplete work, or the user asks "what went wrong" / "retrospective" / "why does this keep happening".

Structured post-failure analysis that identifies root causes and produces durable fixes to process artifacts. Auto-triggers on user-side correction signals ("that's wrong", "you keep doing this", "why did you do that?") AND on agent self-recognized failure signals ("I owe you an apology", "I was wrong about X", "I should have caught this", "I anchored on X and missed Y", "I didn't think it through") — match by meaning, not literal string. Use when a post-merge audit finds issues, the same feedback is given repeatedly, a subagent produces incomplete work, or the user asks "what went wrong" / "retrospective" / "why does this keep happening".

Route a chunk of task-acquired reusable knowledge to the durable artifact that owns it — memory, skill, rule, or doc — via a cited classification rubric, then land it through the right channel (memory in-band; skill/rule/doc edits via a session-backed task, or a direct edit when already inside a suitable session). Invoke explicitly as `/learn <what you learned>`, OR self-trigger when you notice you just acquired reusable knowledge that outlives the current task — after researching a convention, discovering a cross-cutting pattern, resolving an ambiguity that will recur, or receiving a correction that generalizes beyond the immediate fix — and no capture has happened yet this turn. Bounded to fit inside the current turn: classify, dedup-check, land or file, one output line. Never blocks or interrupts the task in progress.

Route a chunk of task-acquired reusable knowledge to the durable artifact that owns it — memory, skill, rule, or doc — via a cited classification rubric, then land it through the right channel (memory in-band; skill/rule/doc edits via a session-backed task, or a direct edit when already inside a suitable session). Invoke explicitly as `/learn <what you learned>`, OR self-trigger when you notice you just acquired reusable knowledge that outlives the current task — after researching a convention, discovering a cross-cutting pattern, resolving an ambiguity that will recur, or receiving a correction that generalizes beyond the immediate fix — and no capture has happened yet this turn. Bounded to fit inside the current turn: classify, dedup-check, land or file, one output line. Never blocks or interrupts the task in progress.

Produce a structured end-of-conversation handoff summary so the next agent (or future-you) can resume cleanly. Use when the user asks for "a summary," "handoff," "what we did," "where do we resume." Auto-trigger when the conversation has shipped 3+ PRs, hit multiple MCP disconnects, run multiple retrospectives, or compaction is approaching.

Produce a structured end-of-conversation handoff summary so the next agent (or future-you) can resume cleanly. Use when the user asks for "a summary," "handoff," "what we did," "where do we resume." Auto-trigger when the conversation has shipped 3+ PRs, hit multiple MCP disconnects, run multiple retrospectives, or compaction is approaching.

Multi-task coordination: parent+subtask decomposition, parallel dispatch planning, dependency-graph navigation, and cross-task scope assessment. Use when: 'decompose mt#X', 'break this down into subtasks', 'coordinate mt#A and mt#B', 'dispatch in parallel', 'dependency order', "what's the order for...", 'run X Y Z in parallel'. Does NOT own single-task lifecycle transitions — those belong to /plan-task, /implement-task, and /verify-task.

Create or update Minsky rules with proper structure, frontmatter, and cross-references. Use when writing a new rule, modifying an existing rule, or reviewing rule quality.

Create or update Minsky rules with proper structure, frontmatter, and cross-references. Use when writing a new rule, modifying an existing rule, or reviewing rule quality.

First-principles product-thinking method for principal-facing Minsky surfaces (cockpit pages/widgets, tray, vitals, future surfaces): derive what a surface SHOULD BE from the principal's supervision loop (triage/decide/steer/verify) instead of dashboard convention. Six moves: job story, owning question (receipts to the record), lightweight HTA (leaf = affordance), altitude (radiator/console/detail), ten decision-forcing X-over-Y principles (needs-me over newest, anomaly over inventory, blast-radius over action-type, ...), Do-Confirm audit (SAGAT freeze test, ISA-18.2 tier discipline, analogy + uniqueness tests). Use when designing or auditing any principal-facing surface, answering 'what should this page/widget be', or running a cockpit redesign/product pass. Sits ABOVE /cockpit-design (entity/visual layer) and /minsky-brand (register); implements the ambient-cockpit RFC's pull-surface discipline.

Blameless postmortem for a production / infrastructure incident — a real outage, degradation, data-loss event, or near-miss affecting shared/prod state or customers. Produces a docs/incidents/<date>-<topic>.md analysis grounded in industry best practice (Google SRE Ch.15, Allspaw blameless culture, Cook "How Complex Systems Fail"): quantified impact, a UTC timeline, contributing factors (NOT a single root cause), and typed action items tracked as Minsky tasks. Use when an incident is RESOLVED and the user asks for a "postmortem", "post-incident review", "PIR", "what caused the outage", "why did it go down", "root cause of the incident", or when a SEV-1/SEV-2 production incident closes. Distinct from /retrospective (agent cognitive / process failures) and /incident-memo (end-of-session cross-incident synthesis).

Blameless postmortem for a production / infrastructure incident — a real outage, degradation, data-loss event, or near-miss affecting shared/prod state or customers. Produces a docs/incidents/<date>-<topic>.md analysis grounded in industry best practice (Google SRE Ch.15, Allspaw blameless culture, Cook "How Complex Systems Fail"): quantified impact, a UTC timeline, contributing factors (NOT a single root cause), and typed action items tracked as Minsky tasks. Use when an incident is RESOLVED and the user asks for a "postmortem", "post-incident review", "PIR", "what caused the outage", "why did it go down", "root cause of the incident", or when a SEV-1/SEV-2 production incident closes. Distinct from /retrospective (agent cognitive / process failures) and /incident-memo (end-of-session cross-incident synthesis).

Myth-first methodology for designing the Minsky marketing site and any adjacent marketing surface (microsites, launch pages, position-paper landing pages). Layers marketing-specific patterns (Idiom B product- screenshot-dominant, left-caption + right-product hero, alternating sections, co-product logo strategy, marketing-format anti-patterns) on top of the `minsky-brand` foundation (locked myth, cultural code, five-layer reference architecture, vocabulary). Consumes the analytical output of `analyze-adjacent-product` for new-surface workshops. Use when designing or auditing any Minsky marketing surface, or workshopping a brand-positioning myth for a new surface. Complements the vendored Tier-1 skills (impeccable / frontend-design / web-design-guidelines / plan-design-review / information-architecture / engineering-writing / seo-skill / motion-framer).

Myth-first methodology for designing the Minsky marketing site and any adjacent marketing surface (microsites, launch pages, position-paper landing pages). Layers marketing-specific patterns (Idiom B product- screenshot-dominant, left-caption + right-product hero, alternating sections, co-product logo strategy, marketing-format anti-patterns) on top of the `minsky-brand` foundation (locked myth, cultural code, five-layer reference architecture, vocabulary). Consumes the analytical output of `analyze-adjacent-product` for new-surface workshops. Use when designing or auditing any Minsky marketing surface, or workshopping a brand-positioning myth for a new surface. Complements the vendored Tier-1 skills (impeccable / frontend-design / web-design-guidelines / plan-design-review / information-architecture / engineering-writing / seo-skill / motion-framer).

Before ending a turn with a question to the user, OR writing a deferred-action recommendation ("I'll file that as a follow-up," "out of scope to address right now," "worth filing separately," "let's track that," "parking lot this," "circle back later," "flag as follow-up") without doing the action in the same turn, classify the draft as Class A (verifiable by lookup), Class B (default already clear from CLAUDE.md / user-preference rule), Class C (genuinely ambiguous principal-stakes choice), or R3 (recommending-instead-of-acting). Act on the classification instead of writing the draft. Use whenever a draft question, "want me to X or Y," "should I," "I'd file that," "we should investigate," "not in scope for current PR but," "for now leaving X as," "noting for later," or any deferral-shaped prose is about to land — OR when a process checklist or gate step asks you to "state a strategy/decision/plan" (a checklist-manufactured trigger that does not read as a deferral).

Before ending a turn with a question to the user, OR writing a deferred-action recommendation ("I'll file that as a follow-up," "out of scope to address right now," "worth filing separately," "let's track that," "parking lot this," "circle back later," "flag as follow-up") without doing the action in the same turn, classify the draft as Class A (verifiable by lookup), Class B (default already clear from CLAUDE.md / user-preference rule), Class C (genuinely ambiguous principal-stakes choice), or R3 (recommending-instead-of-acting). Act on the classification instead of writing the draft. Use whenever a draft question, "want me to X or Y," "should I," "I'd file that," "we should investigate," "not in scope for current PR but," "for now leaving X as," "noting for later," or any deferral-shaped prose is about to land — OR when a process checklist or gate step asks you to "state a strategy/decision/plan" (a checklist-manufactured trigger that does not read as a deferral).

Semiotic analysis of an adjacent product's marketing surface or brand positioning. Encodes the Peirce icon/index/symbol triad, Barthes' three orders of signification (denotation / connotation / myth), and Oswald's cultural-codes framework as the analytical substrate. Names the Pepsi/Arnell trap as the anti-pattern: semiotic vocabulary as post-hoc theater rather than driving reasoning. Use when reading a competitor's marketing site, an inspirational reference, or any adjacent brand you want to understand structurally — for competitive positioning, RFC support, build-vs-buy decisions, or feeding the marketing-site-design workshop's cultural-code identification step. Pairs with marketing-site-design (which consumes this skill's analytical output to drive brand-positioning decisions).

The Minsky brand foundation — locked myth (exocortex / flock), cultural code (Cyberbrain / Section 9), five-layer reference architecture (Ghost in the Shell SAC / Evangelion / Mitsuo Iso / Magilumière / Stross *Accelerando*), bridge-as-affect discipline, code-architecture synthesis, and the locked vocabulary inventory. The agent-consumable tier of the brand foundation: position paper (Notion) is the *strategic* tier, `docs/brand-system.md` is the *operational* tier, this skill is the *agent-consumable* tier. Composes with `pz-voice` (signal — what is claimed); this skill is the channel (how it feels to the audience). Invoke as the strategic anchor for any Minsky-surface design work (`marketing-site-design`, `cockpit-design`) or any artifact that needs to carry the cyberbrain register without re-deriving the workshop output.

Generate and screen a name for a new Minsky primitive — operand, sub-product, microsite, campaign, or marketing surface — using the Lexicon Branding methodology (three-phase identify/invent/implement, sound-symbolism, compound multiplier, processing fluency, polarization test, the diamond exercise, the synchronicity drill) with a mandatory prior-use / trademark-collision screen before any candidate advances. The synthesis dual of analyze-adjacent-product: that skill reads an existing name semiotically, this one generates a new name. Composes with minsky-brand (locked register constraint) and marketing-site-design (surface application). Use when naming a new operand, sub-product, or marketing surface, or evaluating an adjacent product's name.

Semiotic analysis of an adjacent product's marketing surface or brand positioning. Encodes the Peirce icon/index/symbol triad, Barthes' three orders of signification (denotation / connotation / myth), and Oswald's cultural-codes framework as the analytical substrate. Names the Pepsi/Arnell trap as the anti-pattern: semiotic vocabulary as post-hoc theater rather than driving reasoning. Use when reading a competitor's marketing site, an inspirational reference, or any adjacent brand you want to understand structurally — for competitive positioning, RFC support, build-vs-buy decisions, or feeding the marketing-site-design workshop's cultural-code identification step. Pairs with marketing-site-design (which consumes this skill's analytical output to drive brand-positioning decisions).