AGENT SKILL

design-minimalism

The Scope & Out-of-scope stage of the plan-gate — every primitive (class, abstraction, option, new step) in plan.md must be justified by a concrete current-epic use case; speculative additions go to Out of scope. Reached through plan-gate, not as an independent trigger.

适用职业设计师
使用场景视觉设计
License 许可
MIT
所属仓库
muratovv/ai-hats
最近更新
2026-11-05
Stars
★ 3
Forks
1

01 前言 Front Matter

name
design-minimalism
ai_hats
{ "type": "skill", "schema_version": 1 }
license
MIT
description
The Scope & Out-of-scope stage of the plan-gate — every primitive (class, abstraction, option, new step) in plan.md must be justified by a concrete current-epic use case; speculative additions go to Out of scope. Reached through plan-gate, not as an independent trigger.

03 SKILL.md 正文

Design Minimalism

The Scope & Out-of-scope stage of plan-gate: each primitive (class, abstraction, option, new step, new dependency) in a design plan must be justified by a concrete use case in the current epic. Speculative additions ("may be useful for X later", "central registry for future keys", "pre-listed child tasks for unbuilt features") belong in Out of scope with an explicit activation trigger, or are dropped.

This complements trait-se-mindset's "Simplicity first" — that rule is about code; this skill is about the design phase of a task.

When to Use

Reach this stage through plan-gate, not as a standalone brainstorm→plan trigger — plan-gate is the single entry point and routes here to fill the Scope & Out-of-scope section of plan.md.

  • Run it when that section is being written, or a plan proposes new abstractions, options, or sub-systems.
  • Trigger inside it: noticing the urge to "future-proof" or "add for completeness".
  • Sibling stage: requirements-interview owns the adjacent Requirements section — clarify what to build there, how much here.
  • Prior stage: devils-advocate (Approach & counter) runs first and challenges whether the value holds; this stage takes the surviving value as given and minimises the means. Don't re-litigate the value here — challenge scope, not direction.

Checklist

For every primitive in the plan

Ask:

  1. What concrete use case in the current epic does this solve?
    • Answer must point to an explicit acceptance criterion or a named user-facing capability in the current task.
  2. If the answer is "might be useful for X later" / "for a future feature" / "in case we need it":
    • Move to a ## Out of scope section with explicit activation trigger ("re-evaluate when feature X is in scope"), OR
    • Drop it entirely.
  3. If the answer is "for symmetry / completeness":
    • Same — drop or move to Out of scope. Symmetry is not a use case.

The ## Out of scope section is load-bearing

  • Prefer explicit rejection ("rejected because …") over silent omission.
  • This section communicates what we considered and chose not to do — saves future review rounds where someone asks "why didn't you add Y?".
  • A rich Out of scope is a sign of a well-reviewed plan, not bloat.

Worked Example

A plan-design that took seven iterations of rewrites.

User explicitly rejected, across iterations:

Proposed Rejected because
MutableStateEnvelope class speculative — no current step needed mutation
Central state schema with enumerated keys speculative — closed schema blocks user extension
SaveArtifact pipeline step speculative — no current pipeline declared persistence
YAML pipeline manifests speculative — bash-compose covers all current use cases
15 pre-listed child task IDs speculative — child tasks file at start of phase when design is stable

Each was framed as "future-proofing". Each cost user time to read and reject. A ## Out of scope section listing them once with rejection rationale would have saved 5 iterations.

Behavioral delivery: escalation ladder

Code-primitive minimalism (above) tells you "drop speculative classes". Behavioral-delivery tasks — edits to skill text, rule text, prompt shape, HYP data shape, role/trait injection — need a different default: data-only first, abstract only after signal. The ladder lists six rungs from lowest to highest cost. Ship at the lowest rung that covers the observable behavior end-to-end; lift one rung only after a PoC sweep produces signal that the lower rung misses.

When this section applies

Plan-stage of any task that changes how agents observably behave through:

  • a skill / rule text edit;
  • a prompt-shape change (handoff, intake, retro, judge);
  • HYP data shape (a new field on a hypothesis);
  • a role's composition (attached trait, attached skill, injection bullet).

For code-primitive changes (new class, new abstraction, new pipeline step) — the rest of this skill governs.

The ladder

Rung Layer Cost Description
1 text-in-YAML trivial New field round-trips via extra="allow" or a free-form string in an existing config. No schema change.
2 skill text low Edit an existing SKILL.md or add a new one under library/. No engine touch.
3 trait wiring low Attach an existing skill to a trait's composition, or add an injection bullet to a trait. No engine touch.
4 handoff / runner code medium Minimal Python under src/ai_hats/retro/ or src/ai_hats/cli/ to surface or consume a YAML field. Unit-tested.
5 CLI flags medium-high Typed flags on an existing CLI command. Owes e2e coverage.
6 typed schema high Pydantic model fields, migrations, validators. Reserve for "shape is stable and we need rejection at the storage layer".

Don't skip rungs

If rung N suffices to test the hypothesis end-to-end, ship at rung N. Lift to N+1 only when the next sweep's data shows rung N misses signal. "We'll probably want flags later" is not signal — it's level 1–2 speculation in disguise.

Plan-stage shape

Every behavioral-delivery plan.md states the chosen rung explicitly:

Shipping at level N — <one-line why N is sufficient>. Level N+1 not warranted because <PoC signal absent / not yet measured>.

This sentence is the artefact the auditor sweep reads (see the companion HYP authored at document-stage per library-change-hypothesis-protocol).

Case study — the verification-protocol PoC

  • Initial plan (rejected). Extended ValidationLogEntry schema (rung 6) + four typed CLI flags (rung 5) + rewrote four downstream skills (rungs 2–3) + legacy-HYP migration. ~30 min of plan-mode iteration.
  • User redirect. "план сложный. Можем проще как-то сделать?"
  • Shipped plan. Five-step PoC: free-form verification_protocol string under extra="allow" in HYP-*.yaml (rung 1) + lightweight library-change-hypothesis-protocol skill (rung 2) + handoff formatter patch (rung 4, escalated only after the rung-1 PoC showed the data wasn't reaching reviewers). Zero engine schema changes. Same observable behavior.

Lesson: rungs 5–6 looked "carefully abstract" because they encoded the data shape into the model layer. The observable behavior (auditors emit protocol-matching evidence) needed only rungs 1, 2, and 4 — and rung 4 only after rungs 1–2 produced PoC signal that justified the lift. Anything higher would have locked in a shape we hadn't yet observed working.

Anti-Patterns

  • "While we're at it, let's add a --verbose flag" — no concrete current use case.
  • "Central registry for future extension points" — no current consumer.
  • "This class is symmetric with the other one" — symmetry is not justification.
  • Pre-filing child task IDs before the parent plan is approved — premature breakdown.
  • "In case we need this later" abstractions — YAGNI applies to design, not just code.

Completion

A plan passes the minimalism check when:

  • Every primitive has a named current-epic use case (verifiable in acceptance).
  • ## Out of scope section is explicit and lists rejected ideas with rationale.
  • No "future-proofing" rationale survives in the kept-scope section.

See also

  • scope-guard — runtime equivalent: prevents implementation-stage scope creep.
  • trait-se-mindset "Simplicity first" — code-level KISS/YAGNI.
  • predictive-accounting — for shrink/refactor tasks: predict delta + dependency cost before implementation.

04 同仓库更多 Skills

muratovv
muratovv/ai-hats

tool-evaluation-protocol

Time-bounded protocol for evaluating new tools, libraries, or methodologies before adoption. Use when evaluating a candidate dependency for the project, researching a methodology (e.g. ML/LLM frameworks, testing approaches), or following up on a hype-driven recommendation.

★ 3
muratovv
muratovv/ai-hats

systematic-debugging

4-phase bug-fix protocol (evidence, pattern, hypothesis, verify). Use when investigating any error, failure, or unexpected behavior, handling bug reports from users or monitoring, or diagnosing test failures with non-obvious causes.

★ 3
muratovv
muratovv/ai-hats

skill-template

Canonical template and validation guide for ai-hats skills. Use when creating a new skill, reviewing an existing one for structural compliance, or deciding which pattern fits a new behavior.

Skill与智能体开发
★ 3
muratovv
muratovv/ai-hats

skill-optimization

Audit and refactor library components to eliminate redundancy and staleness. Use during periodic library maintenance, after adding multiple new skills or rules, when a role's token budget is too high, or after retrospectives identify component issues.

Skill与智能体开发
★ 3
muratovv
muratovv/ai-hats

silent-fallback-gate

PreToolUse hook — refuses an Edit or Write that adds an inert broad except. Use when a Python edit was blocked for a silent fallback.

★ 3
muratovv
muratovv/ai-hats

retro-to-framework

Convert an observation about agent behavior — from a retrospective or from a single incident — into a framework-level change (hook, rule, skill, skill update). Use after a retrospective identifies problems that are not project-specific, after an incident where an agent misapplied a component it had read, when CLAUDE.md band-aids accumulate (more than 3 per-project rules that could be generic), or when the same problem recurs across multiple projects.

Skill与智能体开发
★ 3