agentleFS
mmnto-aimmnto-ai/totem/.claude/skills/preflight/SKILL.md

preflight

Skill18 starsChanged 52 days agoApache-2.0View on GitHub

Pre-work ritual — spec, search, and (when needed) a 1-page implementation design doc before touching code

50 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use adr, ship and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • asterkinSkill

    adr

    Create Architecture Decision Records (ADRs) following project standards. Guides template usage, process, and best practices for documenting architecturally significant decisions.

    Also in 3 projects that use this

  • AWSSkill

    ship

    Finalize dev work on an issue branch — update docs, push, and open a PR.

    Also in 5 projects that use this

  • MicrosoftSkill

    report

    Turn an exploration (threads, findings, charts) into a single Markdown report — note, blog post, executive summary, KPI dashboard, slide brief, or multi-section analytical report, with embedded charts.

    Also in 3 projects that use this

  • Google CloudSkill

    triage

    Gather context on a change or bug and plan the implementation.

    Also in 4 projects that use this

  • AnthropicSkill

    status

    Case status summary by audience — client-facing (plain language), internal (for the professor), or court-ready (formal caption format per local rules). Same facts, different framing and depth. Use when a student needs to update the client, brief the professor, or prepare a court status report.

    Also in 3 projects that use this

  • GitHubSkill

    refactor

    Surgical code refactoring to improve maintainability without changing behavior. Covers extracting functions, renaming variables, breaking down god functions, improving type safety, eliminating code smells, and applying design patterns. Less drastic than repo-rebuilder; use for gradual improvements.

    Also in 3 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

16 rules. 0 are common, 13 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 45 edited versions we read keep these.

  • 13

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before starting work on issue $ARGUMENTS, execute these phases in order.

    line 6
  2. Distinctive:

    Do NOT write code until all gates are cleared.

    line 7
  3. Very specific:

    Run pnpm exec totem spec $ARGUMENTS to generate the implementation spec from the issue body.

    line 11
  4. Very specific:

    Call mcp__totem-dev__search_knowledge with a query describing the changes you're about to make.

    line 13
  5. Very specific:

    If totem spec fails, report the error and stop — do not proceed to Phase 2.

    line 21
  6. Distinctive:

    No new types or required fields on existing types

    line 28
  7. Distinctive:

    No new state containers (maps, sets, module-level variables, singletons)

    line 29
  8. Distinctive:

    No new failure modes or classes of error

    line 30
  9. Distinctive:

    No new cross-cutting concerns (logging, telemetry, caching, auth)

    line 31
  10. Distinctive:

    When in doubt, draft the doc.

    line 57
  11. Distinctive:

    Tactical path — no approval gate: If tactical, proceed directly to implementation after Phase 2 (triage) completes.

    line 75
  12. Distinctive:

    Lifetime: when created, when mutated, when cleared, when destroyed

    line 115
  13. Distinctive:

    Call out any state that crosses lifecycle boundaries (e.g., a session-level flag consumed by a per-request operation).

    line 118
  14. Distinctive:

    NOT test names. The guarantees you're testing.

    line 138
  15. Distinctive:

    After drafting Phase 3, STOP and output:

    line 160
  16. Distinctive:

    Do NOT write code until the user explicitly approves the design.

    line 166

“Common” is measured: kept by at least 6 in 10 of the 45 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Before starting work on issue $ARGUMENTS, execute these phases in order. Do NOT write code until all gates are cleared.

Phase 1 — Mechanical context gathering

  1. Run pnpm exec totem spec $ARGUMENTS to generate the implementation spec from the issue body. Output lands in .totem/specs/<issue>.md.
  2. Call mcp__totem-dev__search_knowledge with a query describing the changes you're about to make. If the issue touches a specific system (hooks, orchestrator, compiler, extract pipeline, store layer, MCP server), ALSO query mcp__totem-strategy__search_knowledge for relevant ADRs and proposals.
  3. Summarize in 3-5 bullets: what the spec says, which lessons are relevant, and any constraints or traps surfaced by the knowledge queries.

If totem spec fails, report the error and stop — do not proceed to Phase 2.

Phase 2 — Scope triage (decide if Phase 3 is needed)

Skip Phase 3 if this is a tactical change. Tactical means ALL of:

  • Pure bug fix, wording change, or existing-test tightening
  • No new types or required fields on existing types
  • No new state containers (maps, sets, module-level variables, singletons)
  • No new failure modes or classes of error
  • No new cross-cutting concerns (logging, telemetry, caching, auth)
  • Touches ≤3 files in a single architectural layer
  • Leaves the branch-vs-base diff (three-dot against the base, so main moving does not grow it) under the review window (totem review names the cut; 50000 characters of code today, not configurable)

Draft the design doc (Phase 3) if ANY of:

  • Adds a new type, interface, or required field
  • Adds a new state container or changes state ownership/lifecycle
  • Introduces a new failure mode or changes existing error surface (hard error → warning, sync → async, blocking → non-blocking)
  • Crosses architectural boundaries (core → cli, cli → mcp, etc.)
  • Touches >3 files OR introduces a new cross-cutting concern
  • Documents a new config field, new public API method, or new agent-facing tool surface (regardless of whether the doc is in the same PR as the implementation, and regardless of whether the implementation is yours or someone else's)
  • Pushes the branch's diff past the review window, or a fold during the build does: a diff past the window is architectural on SIZE alone, because every reviewer, local and external, reads it in slices and review rounds scale with it. Re-triage when a fold crosses this line, and put the ride-or-split question to the operator WITH its price in rounds (mmnto-ai/totem#3114: a 26-file diff, re-triaged after two reads, took eight external rounds)

When in doubt, draft the doc. The cost of 10 minutes of design writing is always lower than the cost of a multi-round bot review cycle.

Why docs-that-describe-features count as architectural. A wiki page that describes a new config field has the same data-model verification requirement as the code that implements it — you can write incorrect documentation about a real feature surface just as easily as you can write incorrect code. If you're authoring docs for a feature you didn't just build (or built more than a session ago), READ THE SCHEMA before the prose. The Phase 3 data-model section will force you to enumerate the config fields, which is exactly the work that catches "I remember this feature as automatic but the schema says opt-in" errors before they ship to users. The mmnto-ai/totem#1297 docs PR cycle is the load-bearing example.

State your triage decision explicitly: "Tactical — skipping Phase 3" or "Architectural — drafting design doc."

Tactical path — no approval gate. If tactical, proceed directly to implementation after Phase 2 (triage) completes. The Phase 4 approval gate below only applies when Phase 3 was drafted, because the gate exists to catch architectural mistakes before code is written — there's nothing architectural to review for a tactical change. The user's normal PR-approval and merge-approval rules still apply to the finished code.

Architectural path — continue to Phase 3. Draft the design doc, then stop at the Phase 4 approval gate before writing any code.

Phase 3 — Implementation design doc (REQUIRED for architectural changes before code; skipped for tactical)

Append a new ## Implementation Design section to the spec file at .totem/specs/<issue>.md. The section MUST cover all six subsections below. Keep it tight — the whole design section should fit in ~1 page.

Scope (2 sentences)

What this implementation will do, and what it explicitly will NOT do. Negative scope is load-bearing — it prevents scope creep during review.

Data model deltas

List every new type, new field on an existing type, and every new state container (map/set/module variable). For each:

  • What it holds
  • Who writes it
  • Who reads it
  • What invariants hold (required vs optional, bounded vs unbounded, who guarantees the invariant)

Explicitly call out any "reserved keys" or sentinel values — those are collision hazards. Prefer separate fields over reserved keys.

State lifecycle

For each new piece of state, identify:

  • Scope: per-request / per-session / server-lifetime / persistent
  • Lifetime: when created, when mutated, when cleared, when destroyed
  • Ownership: which function/module owns mutation

Call out any state that crosses lifecycle boundaries (e.g., a session-level flag consumed by a per-request operation). Those are the most common source of "one-shot flag consumed before its work succeeded" bugs.

Failure modes

A table. For each failure point:

FailureCategoryAgent-facing surfaceRecovery
<description>init / runtime / transient / permanenthard error / isError / warning / silent degradationhow state returns to healthy

Be exhaustive. Every place the code can throw, return null, return an empty result, or silently succeed with degraded output is a row. If a row has "silent degradation" in the surface column, justify it against Tenet 4 (Fail Loud, Never Drift) or change the design.

Invariants to lock in via tests

NOT test names. The guarantees you're testing. Example:

  • "linked store named 'primary' must not collide with primary failure slot"
  • "init-time warnings survive any reconnect cycle untouched"
  • "one-shot first-query flags are consumed only after successful work"

These become the test assertions. If you can't articulate the invariant in English, you probably don't understand what you're testing yet.

Open questions

Anything that needs user judgment before coding starts. Format:

  • Question: <one sentence>
  • Options: <bulleted list of viable answers with tradeoffs>
  • Recommendation: <your best guess>

Phase 4 — Approval gate (architectural path only)

This phase applies ONLY when Phase 3 was drafted. For tactical changes that skipped Phase 3, there is no gate — see Phase 2.

After drafting Phase 3, STOP and output:

Design doc drafted at .totem/specs/<issue>.md. Please review the Implementation Design section and approve before I start coding. Open questions: <count>.

Do NOT write code until the user explicitly approves the design. If the user wants changes, update the doc and re-stop for approval.

Controller-not-implementer (ADR-063): protect your own decision-making by surfacing architectural questions BEFORE they become bot review findings. A 10-minute design review with the user is strictly cheaper than a 7-round bot review cycle on the PR.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.