mestack

Files (10)

• SKILL.md
• build.md · playbooks/
• fix.md · playbooks/
• investigate.md · playbooks/
• leave-running.md · playbooks/
• reshape.md · playbooks/
• amp.md · references/
• grok.md · references/
• harness.md · references/
• models.md · references/

SKILL.md (first lines)

# mestack

Read [references/harness.md](references/harness.md) once per task to
resolve available capabilities and fallbacks before choosing tools.

## Start

1. Open a todo list. First item: read the Principles index below.
2. Match a playbook. Open its file. Copy its steps into the todo list
   verbatim, before any task-specific todos. A skipped step stays in
   the list with `skip: <reason>`.
3. Name each principle that changes a decision, and the choice it
   changed. Cite only leaves you read this session. A citation with no
   decision is a miss.

If no playbook fits, run the **figure-it-out** skill. Do not invent
a second dispatcher.

## Playbooks

| When | File |
| --- | --- |
| Read-only question: how, why, are we sure | [playbooks/investigate.md](playbooks/investigate.md) |
| Defect to reproduce and fix | [playbooks/fix.md](playbooks/fix.md) |
| New or changed behavior | [playbooks/build.md](playbooks/build.md) |
| Behavior-preserving restructure | [playbooks/reshape.md](playbooks/reshape.md) |
| User is leaving; drive to a finish condition | [playbooks/leave-running.md](playbooks/leave-running.md) |

## Principles

Read the leaf in full when you apply it.

- **Smallest change** (`principle-smallest-change`). Sizing a diff, or
  tempted to add a layer. Delete and shrink first.
- **Named shape** (`principle-named-shape`). Before writing logic: the
  data, the invariant, the structure that makes the rest obvious.
- **Prove on the artifact** (`principle-prove-on-the-artifact`). After
  the work, before done. Run the real thing. The **prove** skill owns
  how.
- **Root cause** (`principle-root-cause`). Debugging. Reproduce first.
  Do not silence the crash.
- **Attack the premise** (`principle-attack-the-premise`). Two fixes
  on one belief failed the same check. Test the belief, not a third
  fix.
- **Test behavior** (`principle-test-behavior`). Writing or keeping a
  test. Fails when behavior breaks, survives a refactor.
- **Explain the number** (`principle-explain-the-number`). Before
  reporting a measurement. Name the limiter, rule out other readings.
- **Parent owns fan-out** (`principle-parent-owns-fan-out`). Any
  parallel work. Children do not spawn children.
- **Reversible without asking** (`principle-reversible-without-asking`).
  Tempted to ask permission for work you can undo. Do it, show the
  result.
- **Encode the rule** (`principle-encode-the-rule`). About to write the
  same instruction twice. Put it in a check, not more prose.
- **One home** (`principle-one-home`). A fact already lives somewhere.
  Point at it. Do not copy it.
- **Boundary discipline** (`principle-boundary-discipline`). Wiring
  CLI, config, network, or adapters. Validate at the edge.
- **Build the lever** (`principle-build-the-lever`). Non-trivial
  work. The artifact is a rerunnable tool.
- **Exhaust the design space** (`principle-exhaust-the-design-space`).
  No precedent. Compare two or three real alternatives.
- **Experience first** (`principle-experience-first`). Product or
  API tradeoff. Consumer result over a cheaper implementation.
- **Guard the context window** (`principle-guard-the-context-window`).
  Large reads or fan-out. Parent keeps pointers, not dumps.
- **Make operations idempotent** (`principle-make-operations-idempotent`).
  Commands, startup, loops. Retries converge.
- **Migrate then delete** (`principle-migrate-callers-then-delete-legacy-apis`).
  Replacing an internal API. One wave, no dual path.
- **Minimize reader load** (`principle-minimize-reader-load`). Hard
  to trace. Cut layers and hidden state.
- **Outcome-oriented execution** (`principle-outcome-oriented-execution`).
  Planned rewrite. Converge on the target, not throwaway middles.
- **Redesign from first principles**
  (`principle-redesign-from-first-principles`). New requirement.
  Integrate as if it had always been there.
- **Separate before serializing**
  (`principle-separate-before-serializing-shared-state`). Concurrent
  writers. Split ownership before adding a lock.
- **Sequence verifiable units** (`principle-sequence-verifiable-units`).
  Sweeps, migrations, commit order. Each unit ends in a check.
- **Type system discipline** (`principle-type-system-discipline`).
  Types and signatures. Illegal states must not compile.

## Routing

- Nontrivial subsystem you do not yet understand: the **how** skill.
- After implementation or a claimed fix: the **prove** skill.
- No project `verify-*` skill, and the repo has a runnable app:
  **create-verification-skill**. Prove offers this once; do not
  generate it as a side effect of a fix.
- Feature map or verify skill drifted: **maintain-verification-skill**.
- Parallel coverage or competing attempts: parent spawns, unique output
  paths, then the parent reads and synthesizes. See harness.md.
- Large or cross-cutting run, even if a small version would be fix or
  build: **figure-it-out**.
- Concurrency, retries, state machines, parsers, or unsafe code where
  tests cannot reach the bad case: **create-formal-verification-skill**
  (once per repo), then that project `formal-*` skill. Drifted:
  **maintain-formal-verification-skill**.
- Measured a speedup or regression: **benchmark-checklist** before
  reporting it.
- The user corrected the same mistake twice: **correct**.
- Adversarial review of a change: **interrogate**.
- Catch-up on recent work: **recall**. Catch-up within this chat:
  **ketchup**. Teach-me: **teach**. Explicit TDD: **tdd**.
- Opening a PR, committing, pushing, or contacting anyone: only when
  the user asked for that action.

## Autonomy

Proceed on reversible work. Pause for force-push to shared branches,
deploys, data deletion, and messages to other people.

"Don't stop", "going to bed", "run until done": the leave-running
playbook. Log via **show-me-your-work**.

From kevherro/mestack, MIT.

More from kevherro/mestack