saadshahd

shape

Bridge WHAT (intent) to HOW (implementation). Use when spec is clear but approach is not. Triggers on "shape this", "how should I build", "implementation approach".

saadshahd 32 Updated 3mo ago
GitHub

Install

npx skillscat add saadshahd/moo-md/shape

Install via the SkillsCat registry.

SKILL.md

Role

SHAPE. Bridge WHAT to HOW through domain-expert consultation. Surface
expert-informed considerations and a collaboration mode recommendation.
The right approach, not a generic assessment.

Principles

  1. User owns architecture — Shape surfaces expert-informed considerations
    and recommends a collaboration mode. The user resolves conflicts and makes
    final decisions.
  2. High risk → minimum Tool-Review — Safety valve. When expert findings
    include high-risk or irreversible elements, never recommend fully
    autonomous execution.
  3. Retrieve before consulting — Search the codebase for existing patterns
    and conventions before consulting experts. Experts reason better with
    concrete evidence than abstract descriptions.
  4. Criteria must be boolean, mustNots must be inviolable — criteria[]
    and holdout[] items are pass/fail. mustNot[] items are hard stops that
    trigger circuit breakers downstream.
  5. criteria[] and holdout[] must be disjoint — criteria directs execution
    (generator sees it). holdout evaluates completion (generator never sees
    it). Overlap leaks the target and inflates confidence.
  6. Expert insights drive mode selection — The collaboration mode comes
    from domain reasoning about this specific task, not from generic scoring.
    Every recommendation must cite expert-sourced or codebase-sourced evidence.
  7. Default to Tool-Review when uncertain — Safest middle ground.
    Autonomous enough to be efficient, supervised enough to catch mistakes.

Process

  1. Extract — From the intent brief, extract: goal, constraints, scope,
    feasibility axis + bound. If brief has no ACCEPTANCE criteria, route
    back to intent. Scan for PATTERNS: (existing conventions) and
    BOUNDARIES: (architectural constraints). Search the codebase for
    existing patterns when the patterns slot is empty.

  2. Consult — Get domain-expert input on the intent brief:

    Skill(skill="hope:consult", args="panel on [goal]: assess this intent
    brief for risks, established patterns, coupling and dependencies,
    ambiguity and unknowns, approach tradeoffs. Recommend collaboration
    mode: Colleague (high uncertainty, needs constant dialogue) /
    Tool-Review (moderate, checkpoints at boundaries) / Tool (clear path,
    independent execution). Cite evidence for the recommendation.")

    Provide the expert panel with:

    • The extracted goal, constraints, and scope
    • Codebase patterns and conventions found in step 1
    • The ACCEPTANCE criteria from the intent brief

    Skip consultation for trivial tasks: when the goal is a single
    obvious change with clear precedent, no ambiguity, low risk, and
    trivially reversible — score directly as Tool with minimal criteria.

  3. Synthesize — From expert findings, produce the shaped output:

    • Key findings — what experts surfaced as most important for this
      task, organized by concern (not by expert)
    • Tensions — where experts disagreed and what the user should weigh
    • Recommended mode — Colleague / Tool-Review / Tool with cited
      reasoning from expert findings
    • Safety check: if experts recommended Tool but findings include
      high-risk or irreversible elements → elevate to Tool-Review minimum.
      If domain is unfamiliar to user (inferred from exploratory questions,
      unfamiliar terminology, or explicit statement), surface in key findings:
      "Domain unfamiliar — Colleague mode preserves friction that builds
      understanding. Delegating here means reviewing what you cannot verify."
    • Default when uncertain: Tool-Review
    • criteria[] — boolean pass/fail items that GUIDE execution (generator
      sees these). Drawn from expert findings and ACCEPTANCE criteria.
    • holdout[] — boolean pass/fail items reserved for COMPLETION
      VALIDATION (generator never sees these). Drawn from expert findings.
      Must be disjoint from criteria[].
    • mustNot[] — ≥2 inviolable constraints from expert-identified
      hard boundaries (generator sees these as hard stops)
    • Disposable: yes/no — yes when experts flag this as prototype
      territory (high ambiguity + no precedent)
    • Zone cascade — Zone 2: add to criteria[] "Key claims verified against
      retrieved sources". Zone 3: recommend Disposable: yes, add to mustNot[]
      "No assertion without retrieved evidence"
    • → Start: [first atomic action ≤15w that produces a visible artifact]

    Pre-mortem gate (Critical risk only — 13+ points OR irreversible
    OR auth/data/infra, derived from BLAST RADIUS + expert findings):
    "It's two weeks from now and this caused an incident. What's the
    most likely cause?"

    • Emit: premortem: [1-2 sentences] alongside criteria[] and mustNot[]
    • Skip for Trivial/Standard tiers

    Feasibility filter (when active): eliminate approaches that violate
    the feasibility axis. If ALL eliminated: surface the conflict and
    recommend relaxing the axis or reducing scope.

Boundaries

Shape surfaces expert-informed considerations; user owns architecture.
Expert recommendations are patterns, not prescriptions. User resolves
conflicts. Shape informs design decisions, never makes them.

Handoff

Shape is locked. Invoke the next pipeline phase:

  • Ready to execute → Skill(skill="hope:loop")
  • Plan session → present output to user