@se-studio/skills 1.9.9 → 1.9.10

package/skills/coding-discipline/SKILL.md

@@ -391,7 +391,7 @@ When making changes, update the relevant documentation:
 - [Core Data Types Docs](./packages/core-data-types/README.md) — LLM ref: [docs/llms.md](./packages/core-data-types/docs/llms.md)
 - [Core UI Docs](./packages/core-ui/README.md) — LLM ref: [docs/llms.md](./packages/core-ui/docs/llms.md)
 - [A/B Testing Docs](./packages/ab-testing/README.md) — LLM ref: [docs/llms.md](./packages/ab-testing/docs/llms.md)
-- [HubSpot Docs](./packages/hubspot/README.md) — LLM ref: [docs/llms.md](./packages/hubspot/docs/llms.md)
+- [HubSpot Docs](./packages/hubspot/README.md) — LLM ref: [docs/llms.md](./packages/hubspot/docs/llms.md) (optional package; **not** the fleet default forms provider)
 - [Search Docs](./packages/search/README.md) — LLM ref: [docs/llms.md](./packages/search/docs/llms.md)
 - [Markdown Renderer Docs](./packages/markdown-renderer/README.md) — LLM ref: [docs/llms.md](./packages/markdown-renderer/docs/llms.md)
 - [Contentful CMS CLI Docs](./packages/contentful-cms/README.md)
@@ -404,7 +404,7 @@ When working in a project that installs `@se-studio` packages, tell LLMs to read
 - `node_modules/@se-studio/core-data-types/docs/llms.md`
 - `node_modules/@se-studio/core-ui/docs/llms.md`
 - `node_modules/@se-studio/ab-testing/docs/llms.md`
-- `node_modules/@se-studio/hubspot/docs/llms.md`
+- `node_modules/@se-studio/hubspot/docs/llms.md` (only when the site uses HubSpot)
 - `node_modules/@se-studio/search/docs/llms.md`
 - `node_modules/@se-studio/markdown-renderer/docs/llms.md`
 

package/skills/contentful-cms-core/SKILL.md

@@ -867,6 +867,17 @@ cms-edit index dump --reference-only          # Full catalog snapshot in termina
 
 If someone else also changed an entry, ask all versus mine and `publish choose`. The Contentful role must allow it. Unpublish, archive, and revalidate use the same plan-then-yes rule. Do not apply a plan on your own.
 
+### Before a production promote
+
+When pages that use **templates**, **person** entries, or other linked content are about to go live, verify publish state **before** merging the promote (release verification rule 1):
+
+1. List the page(s), linked **template**(s), **person** / person-type entries, and any other content stack pieces the live render walks.
+2. Confirm each is published in the production environment with no pending drafts — compare CDA (Delivery) vs CPA (Preview), or use `@se-studio/site-check/publish-state` / `check-publish-state`.
+3. Record results on the promote PR. A Nick override never skips this check.
+4. Do not assume publishing the page alone published a shared template or person — those often need their own publish (and template webhooks refresh pages that use them).
+
+See `packages/skills/references/agent-session/release-verification.md` and `docs/editor-tasks/publish-handoff.md` (in contentful-cms).
+
 ## Concurrent Sessions
 
 Use `--session <name>` or `CONTENTFUL_CMS_SESSION=<name>` to isolate parallel workflows.

package/skills/how/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: how
+description: "Use for \"how does X work\", code walkthroughs before changing something, and placement / ownership / layering questions (\"where should this live\", \"which package owns this\", \"is this the right layer\"). Explains subsystem architecture, runtime flow, onboarding mental models. Use why for motivation."
+---
+
+# How
+
+
+## SE Studio vendoring notes
+
+- Upstream frontmatter `disable-model-invocation: true` moved out of YAML (SE Studio skills allow only name + description).
+- **SE Studio trial: Auto only.** Omit `model` on Task spawns. Do not create or read `pstack-models.mdc` / run `setup-pstack`. Never use `xhigh` or `max`.
+- Soft-dep **`why`**: description mentions it for motivation questions. **`why` is not in this trial install** — skip if missing; answer motivation from PR/commit history and code comments instead. Do not install `why` to satisfy the reference.
+- **Trial spend posture (keep `/how` value; make cost explicit):** complex `/how` can spawn 2–4 explorers + 1 explainer ≈ **up to 5 Auto Tasks**. Prefer the simple path when in doubt. Cap explorers at **4**. Log multi-explorer `/how` runs in the two-week trial spend notes. Prefer fewer angles over silent truncation of depth.
+
+Explore the codebase to answer "how does X work?" questions. Produce architectural explanations at the level of a senior engineer onboarding onto a subsystem, enough to build a working mental model, not so much that it reads like annotated source code.
+
+Every spawn is a Task subagent with `subagent_type: generalPurpose` and `readonly: true`. **SE Studio trial:** omit `model` on every spawn (`auto` / `inherit-parent`). Do not read or create `~/.cursor/rules/pstack-models.mdc`. Do not use `xhigh` or `max` tiers. Upstream defaults (`grok-4.7-xhigh-fast` / `claude-opus-5-5-xhigh`) are **forbidden** for this trial.
+
+## 1. Assess complexity
+
+If the scope is ambiguous, state your interpretation and explore. The user can redirect.
+
+- **Simple** (a single module, a small utility, a narrow question such as "how does function X work"): no explorers. Spawn one explainer that explores and explains in one pass, built from `references/explainer-prompt.md` without the explorer-findings section. Go to step 4.
+- **Complex** (a subsystem spanning multiple files or services, a cross-cutting feature, a full architectural overview): go to step 2. Budget: 2–4 explorer Tasks + 1 explainer Task (max **5** Auto Tasks for one `/how`). Prefer 2 explorers when two angles cover the question.
+
+When in doubt, take the simple path.
+
+## 2. Explore (complex only)
+
+Decompose the question into 2 to 4 angles, each a distinct slice of the subsystem. Spawn all explorers in a single message, each with `references/explorer-prompt.md` and its angle filled in. Do not exceed 4 explorers.
+
+## 3. Synthesize (complex only)
+
+Once all explorers have returned, spawn one explainer with `references/explainer-prompt.md` and every explorer's findings filled in.
+
+## 4. Present
+
+Present the explainer's output. Light edits for clarity or context from the conversation are fine. Do not substantially rewrite it.
+
+## Output format
+
+The explanation uses the sections defined in `references/explainer-prompt.md`, dropping any that do not apply: Overview, Key Concepts, How It Works, Where Things Live, Gotchas.

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

@@ -0,0 +1,55 @@
+# Explainer Prompt Template
+
+Build the explainer subagent's prompt from this template. Fill in the placeholders.
+
+---
+
+You are writing an architectural explanation for a senior engineer. Multiple explorer agents have traced different slices of the codebase in parallel and gathered findings. Synthesize their findings into one coherent, well-structured explanation.
+
+## Original Question
+
+> {QUESTION}
+
+## Explorer Findings
+
+{EXPLORER_FINDINGS_ALL}
+
+## Instructions
+
+The explorers each investigated a different angle of the same subsystem. Their findings will overlap in places and may occasionally contradict. Reconcile them. Merge overlapping descriptions, resolve contradictions by checking the code yourself, and combine the separate slices into a unified picture.
+
+Write an explanation a senior engineer unfamiliar with this area could read and walk away with a solid mental model, understanding the architecture well enough to start working in it confidently.
+
+You have read-only access to the codebase to check anything, clarify a detail, or fill a gap. Use Read, Grep, and Glob as needed. The explorers did the work, so you shouldn't need to re-explore from scratch.
+
+## Output Format
+
+Use this structure, adapted to what makes sense for the question. Not every section is needed for every question.
+
+### Overview
+1-2 paragraphs. What is this thing, what does it do, why does it exist. Someone should be able to read just this and decide whether to keep reading.
+
+### Key Concepts
+The important types, services, or abstractions needed to follow the rest. Brief definitions, not exhaustive.
+
+### How It Works
+The core of the explanation, and the longest section. Walk through the flow: what triggers it, what happens step by step, where data goes, what the decision points are.
+
+Use prose, not pseudocode. Reference specific files and functions so the reader knows where to look, but don't dump large code blocks unless a snippet is essential to a point.
+
+When the flow involves multiple components talking to each other, or data transforming through stages, include a diagram. Use mermaid (```mermaid) for structured flows (sequence diagrams, flowcharts, component graphs) or ASCII art for simpler relationships where mermaid would be overkill. Use your judgment. A diagram should clarify, not decorate. If prose covers the flow, skip the diagram.
+
+### Where Things Live
+A brief file/directory map. Just the ones someone would need to start working here.
+
+### Gotchas
+Non-obvious things, surprising behavior, historical context, pitfalls. Skip this section if there's nothing worth calling out.
+
+## Communication Style
+
+- Use concrete language, not abstractions-about-abstractions
+- Say "the `UserService` calls `AuthClient.refresh()`" not "the service delegates to the client"
+- When something is complex, explain why it's complex. Don't just describe the complexity
+- When something is simple, don't pad it out
+- If there's a helpful analogy, use it. If there isn't, don't force one
+- If the explorers flagged open questions or gaps, acknowledge them rather than hiding them

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

@@ -0,0 +1,35 @@
+# Explorer Prompt Template
+
+Build each explorer subagent's prompt from this template. Fill in the placeholders.
+
+---
+
+Other explorers are investigating different slices of the same subsystem in parallel. Don't try to cover everything. Focus on your assigned angle and go deep.
+
+## Question
+
+> {QUESTION}
+
+## Your Exploration Angle
+
+{EXPLORATION_ANGLE}
+
+## Output
+
+### Components Found
+The key types, services, classes, and abstractions. For each: name, file path, and a one-sentence description of what it does.
+
+### Flow
+The execution flow step by step. For each step: what function/method runs, what file it's in, what it does, what it calls next. Include the data that flows between steps.
+
+### Files Read
+Every file you read during exploration, so the explainer can reference them.
+
+### Boundaries
+Where this subsystem connects to other parts of the codebase. The inputs and outputs.
+
+### Non-Obvious Things
+Anything surprising, historically motivated, or easy to get wrong. Things that look like they should work one way but work another.
+
+### Open Questions
+Anything you couldn't fully trace or understand. Be honest about gaps.

package/skills/interrogate/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: interrogate
+description: "Use for \"interrogate\", \"adversarial review\", \"multi-model review\", \"challenge this\", \"stress test this code\", \"find blind spots\", or \"tear this apart\". Multiple LLM reviewers challenge changes from independent angles."
+---
+
+# Interrogate
+
+Spawn reviewers to adversarially review code changes. In the SE Studio trial the adversarial signal is independent review passes on Auto, not model diversity. The deliverable is a synthesized verdict. Do NOT auto-apply changes.
+
+## SE Studio vendoring notes
+
+- Upstream frontmatter `disable-model-invocation: true` moved out of YAML (SE Studio skills allow only name + description).
+- **SE Studio trial: Auto only.** Never create or read `~/.cursor/rules/pstack-models.mdc`. Never run `setup-pstack`. Never use `xhigh` or `max` model tiers. Cap reviewers at **1 or 2**, both `auto` / `inherit-parent` (omit `model` on Task).
+
+## Step 1, Scope
+
+Identify what to review from context:
+
+- If the user points at specific files or a diff, use that.
+- If on a feature branch, run `git diff main...HEAD` (or the appropriate base branch — for se-core-product use `dev`) for the full changeset.
+- If the user's message references recent work, gather the relevant files.
+
+Package the diff or file contents with any surrounding context files the reviewers need to understand the code.
+
+## Step 2, Intent
+
+Before spawning reviewers, state the intent in one clear paragraph from the user's message, commit messages, the PR description if one exists, and the code. If you're unsure about the intent, ask the user before proceeding.
+
+## Step 3, Spawn Reviewers
+
+**SE Studio trial defaults (authoritative — ignore any local `pstack-models.mdc`):**
+
+| Subagent | Default model | When |
+|----------|---------------|------|
+| Reviewer A | `auto` / `inherit-parent` (omit `model`) | Always |
+| Reviewer B | `auto` / `inherit-parent` (omit `model`) | Optional second pass when the user asks for dual review or the change is large; otherwise skip |
+
+Do **not** fall back to `claude-opus-5-5-xhigh`, `grok-4.7-xhigh-fast`, or any other xhigh/max slug. Panel size is **1 or 2** max.
+
+Each reviewer gets `subagent_type: generalPurpose`, `readonly: true`, and **no** `model` field (inherit parent / Auto). Label them Reviewer A (and B if used).
+
+Read `references/reviewer-prompt.md` and fill in the same template for every reviewer with the stated intent, the diff or file contents, the rubric from `references/rubric.md`, and the code-quality lens from `references/code-quality-review.md`.
+
+## Step 4, Synthesize
+
+As results come back, build a unified picture. Parse every reviewer's findings. Merge findings that describe the same issue differently, and note which reviewer raised each one. Findings two reviewers raised independently are the highest signal when dual review was used. Note disagreements.
+
+## Step 5, Lead Judgment
+
+You are the lead reviewer, a pragmatic senior engineer, not a neutral aggregator. Read `references/lead-judgment.md` for the full framework. Put every finding in one of four buckets, with the reviewer(s) that raised it and a one-line rationale.
+
+- **Act on**. Real issues affecting correctness, security, or maintainability given the actual goals. They would block a real PR.
+- **Consider**. Legitimate, but you're not sure they outweigh the cost of addressing them now. Worth the user's attention.
+- **Noted**. Technically valid but not actionable. Context-dependent, premature optimization, or low-impact at this stage.
+- **Dismissed**. Wrong, nitpicky, or missing context, with a brief reason.
+
+## Output Format
+
+### Intent
+> [The stated intent paragraph from Step 2]
+
+### Reviewers
+- Reviewer [label]: [model name], [N findings] (one bullet per reviewer)
+
+### Act On
+[Each: description, which reviewers raised it, why it matters.]
+
+### Consider
+[Each: description, which reviewers raised it, the tradeoff.]
+
+### Noted
+[Brief list.]
+
+### Dismissed
+[Each with a brief rationale.]
+
+### Agreement Map
+[Where reviewers agreed and diverged, and what that pattern tells us.]

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

@@ -0,0 +1,47 @@
+# 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.
+
+## 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/interrogate/references/lead-judgment.md

@@ -0,0 +1,58 @@
+# Lead Judgment Framework
+
+You are the lead reviewer. The configured 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/interrogate/references/reviewer-prompt.md

@@ -0,0 +1,62 @@
+# 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}
+
+Review 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.
+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, only if you have a concrete alternative.
+
+A good finding references specific code, not vague concerns ("this could be better"). 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.
+
+Do not restate what the code does without identifying a problem. Do not praise the code. If you find nothing wrong, say "no findings" and stop. An empty review is a valid outcome.
+
+## Output
+
+Return your findings as a structured list:
+
+```
+## 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/interrogate/references/rubric.md

@@ -0,0 +1,77 @@
+# Review Rubric
+
+Review through whichever lenses are relevant. Not every lens applies to every change.
+
+## 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
+- Do both the happy path and 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," a reconciliation step is missing.
+- 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 follow the call chain, read the types, and 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
+- A workaround: why is it 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?
+- Bolted-on vs. integrated: if the new requirement had been known from the start, would the code look like this, or does the change feel patched onto the existing design?
+- 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.
+
+## Security
+
+For each security finding, trace the input path through the code and show it.
+
+- 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/principle-boundary-discipline/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: principle-boundary-discipline
+description: "Apply when wiring validation, error handling, or framework adapters. Concentrate guards at system boundaries (CLI, config, network, external APIs); trust internal types and keep business logic in pure functions."
+---
+
+# Boundary Discipline
+
+
+## SE Studio vendoring notes
+
+- Upstream frontmatter `disable-model-invocation: true` moved out of YAML (SE Studio skills allow only name + description).
+
+Place validation, type narrowing, and error handling at system boundaries. Trust internal code unconditionally. Business logic lives in pure functions. The shell is thin and mechanical.
+
+**Why:** Scattered validation is noisy, redundant, and gives a false sense of safety. Keep logic out of framework wiring so it can be tested without the framework.
+
+**The pattern:**
+- **At boundaries** (CLI args, config files, external APIs, network protocols): validate, return errors, handle defensively.
+- **Inside the system:** typed data, error propagation, no re-validation. Trust the types.
+- **Across the boundary.** Expose domain concepts, not the boundary's private representation. Keep general-purpose mechanism inside and special-purpose policy at the edge.
+
+**Applications:**
+
+Validation and error handling:
+- Validate config at parse time (the boundary), not inside business logic
+- Parse raw data into domain types at the boundary
+- Do not re-export transport, storage, framework, or wire types through the public surface
+- No redundant nil checks deep in call chains if the boundary already validated
+
+Code organization:
+- Business logic in pure functions with no framework dependencies
+- Parse functions: pure transforms from raw bytes to typed state
+- Prompt construction: structured state in, string out
+- Scoring and assessment: pure transforms from state to results
+
+**The tests:**
+- "Is this data crossing a system boundary right now?" If not, validation is redundant.
+- "Can this be a pure function that the shell just calls?" If yes, extract it.

package/skills/principle-encode-lessons-in-structure/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: principle-encode-lessons-in-structure
+description: "Apply when you catch yourself writing the same instruction a second time, or notice a recurring correction. Encode the rule as a lint, metadata flag, runtime check, or script instead of more text."
+---
+
+# Encode Lessons in Structure
+
+
+## SE Studio vendoring notes
+
+- Upstream frontmatter `disable-model-invocation: true` moved out of YAML (SE Studio skills allow only name + description).
+
+If the lesson needs judgment and cannot be encoded, make the instruction more prominent and add an example of the failure mode.
+
+**Corollary:** If the fix is structural, only use the structural fix. The instruction is the symptom.

package/skills/principle-fix-root-causes/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: principle-fix-root-causes
+description: "Apply when debugging. Trace each symptom to its root cause and fix it there; reproduce first, ask why until you reach it, resist nil-check guards that silence crashes."
+---
+
+# Fix Root Causes
+
+
+## SE Studio vendoring notes
+
+- Upstream frontmatter `disable-model-invocation: true` moved out of YAML (SE Studio skills allow only name + description).
+
+When debugging, do not fix symptoms. Trace every problem to its root cause and fix it there.
+
+**Why:** Symptom fixes accumulate. Each workaround makes the system harder to reason about, and the real bug remains. Root-cause fixes are slower upfront but reduce total debugging time.
+
+**Pattern:**
+- Reproduce first
+- Ask "why" until you hit the root cause
+- Do not add guards (adding a nil check to silence a crash is a symptom fix)
+- If a workaround needs a paragraph-long comment to justify it, the code is wrong (fix the code, not the comment)
+- Check for the pattern, not just the instance (grep for the same pattern, fix all instances)
+- When stuck, instrument. Don't guess (add logging, read the actual error)
+
+**Restart bugs: suspect state before code**
+
+When something "fails after restart," suspect stale persistent state first: config files, caches, lock files, serialized state. If clearing a state file restores behavior, prioritize state validation as the fix.

package/skills/principle-guard-the-context-window/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: principle-guard-the-context-window
+description: "Apply when context is filling up: large outputs, long files, repeated reads, fan-out planning. Route bulk to subagents; keep summaries in the main thread, not raw payloads."
+---
+
+# Guard the Context Window
+
+
+## SE Studio vendoring notes
+
+- Upstream frontmatter `disable-model-invocation: true` moved out of YAML (SE Studio skills allow only name + description).
+
+**Why:** Context overflow degrades reasoning quality, creates compression artifacts, and halts progress.
+
+**Pattern:**
+- **Size phases and cap scope.** Limit files per phase, set turn budgets, account for mechanism costs.

package/skills/principle-make-operations-idempotent/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: principle-make-operations-idempotent
+description: "Apply when designing commands, lifecycle steps, or processing loops that run amid crashes, restarts, and retries. Converge to the same end state regardless of partial prior runs."
+---
+
+# Make Operations Idempotent
+
+
+## SE Studio vendoring notes
+
+- Upstream frontmatter `disable-model-invocation: true` moved out of YAML (SE Studio skills allow only name + description).
+
+Design operations so they converge to the correct state regardless of how many times they run or where they start from. Every state-mutating operation should answer: "What happens if this runs twice? What happens if the previous run crashed halfway?"
+
+**Why:** Commands, lifecycle operations, and processing loops run where crashes, restarts, and retries are normal. If partial state changes the next run's outcome, every restart becomes a debugging session.
+
+**The pattern:**
+- Convergent startup: scan for existing state, clean stale artifacts, adopt live sessions
+- Content-based cleanup: compare by content equivalence, not creation order
+- Self-healing locks: use PID-based stale lock detection
+- Idempotent scheduling: failed work respawns cleanly, fresh input regenerated after each cycle
+
+**The test:**
+1. What happens if this runs twice in a row?
+2. What happens if the previous run crashed at every possible point?
+3. Does re-execution converge to the same end state?
+
+If any answer is "it depends on what state was left behind," the operation needs a reconciliation step.