Skip to main content

Fool Stack

Fool-proof new-feature delivery from a human-approved specification through coordinated implementation and compact Playwright acceptance coverage, with mandatory human clarification whenever requirements are ambiguous. Use when the user invokes /fool-stack or asks to build a frontend feature with spec-driven development, Matt Pocock's GrillMe/Grilling interview, the repository's implement-feature workflow, and Playwright Planner, Generator, and Healer agents.

Source: .agents/skills/fool-stack/SKILL.md

Metadata​

  • name: fool-stack

Content​

Fool Stack

Deliver a new feature through three ordered stages: specify the behavior, implement the approved specification, then prove the important business flow with compact Playwright coverage. Never let an AI agent silently invent or approve expected behavior.

Non-negotiable sequence​

GrillMe interview -> Markdown specification -> human approval
-> implement-feature hard gate -> implementation -> touched-file refactor -> QA and review
-> Playwright Planner -> plan conformance review -> Generator -> Healer -> full gates

Do not skip ahead. If a stage is blocked, preserve the completed artifacts and return the smallest concrete decision to the human.

Human clarification rule​

Never guess a requirement. When doubt could change user-visible behavior, scope, acceptance criteria, roles or permissions, data ownership, external side effects, destructive actions, or the meaning of “done,” pause the affected work and ask the human.

Before asking, inspect the repository, linked requirements, existing feature behavior, and documented conventions. Resolve discoverable technical facts yourself; do not ask the human to perform code discovery. If two or more behaviorally meaningful interpretations remain, the requirement is ambiguous even when one seems likely.

Ask one concise question at a time and include:

  • the exact ambiguity;
  • the evidence or conflicting interpretations;
  • the recommended answer and its tradeoff;
  • what work is paused until the answer is recorded.

Do not let the coordinator, an implementation subagent, or a Playwright agent choose on the human's behalf. Record the answer in the durable specification, update affected acceptance criteria and plans, obtain approval when behavior changed, then resume from the paused stage.

This rule does not require human approval for ordinary implementation details already determined by repository rules, approved interfaces, or established local patterns. Escalate only when the unresolved choice changes the product contract or authorized scope.

Stage 1: Specify the feature​

  1. Read the repository rules and load the applicable feature context before investigating the change.
  2. Locate the existing source of truth: PRD, Lark task, feature reference, or feature-specific Markdown. Do not create a competing source of truth when one already exists.
  3. Load the available Matt Pocock GrillMe/Grilling skill and follow it faithfully:
    • Ask one question at a time.
    • State the recommended answer and its tradeoff.
    • Discover repository facts directly instead of asking the human to find them.
    • Continue until the behavior and boundaries are shared understanding.
  4. Write or update a durable Markdown specification containing only what is relevant:
    • problem, outcome, actors, permissions, and terminology;
    • goals and explicit non-goals;
    • concrete examples and acceptance criteria;
    • happy path, important alternate states, validation, and failure behavior;
    • affected routes, API mode, dependencies, and test-data needs;
    • unresolved decisions and assumptions.
  5. Present a compact summary and the unresolved decisions to the human.
  6. Stop for explicit human approval. Do not implement, generate acceptance tests, or treat silence as approval.

If the human changes behavior later, update the Markdown and obtain approval again before continuing.

Stage 2: Implement the approved specification​

  1. Load .agents/skills/implement-feature/SKILL.md completely and execute it as the coordinator. Do not reproduce a weaker version of that workflow here.
  2. Give its planning agents the approved specification as the behavioral source of truth. Include the Human clarification rule in every subagent handoff so requirement uncertainty returns to the coordinator and human instead of becoming an implementation assumption.
  3. Complete every implement-feature hard-gate item before coding.
  4. When a hard-gate item is blocked, stop and ask for human review with a compact table:
ItemEvidenceWhy blockedRecommended decision
Hard-gate itemRepository or external evidenceMissing fact or authoritySmallest safe decision

The human may supply the missing input, approve an explicit not-applicable determination, or narrow the feature. Record that decision in the implementation plan. Neither the coordinator nor a subagent may waive the gate.

  1. After the gate passes, let implement-feature coordinate implementation, page-level verification, QA, code review, integration, and durable feature-context updates.
  2. For each implementation slice, make the approved behavior green first, then perform the touched-file refactor pass below before QA and code review. The implementing subagent owns both steps; the coordinator still does not write implementation code.
  3. Treat implementation-stage Playwright checks as developer feedback. The Playwright-agent stage below is the final acceptance-authoring pass against the integrated feature.

If implementation reveals a specification contradiction, return to Stage 1. Do not heal the contradiction in code or tests.

Touched-file refactor pass​

Refactor only files touched by the feature and the smallest directly related files required to keep imports, tests, and tooling valid. Do not turn this pass into an unrelated repository-wide migration.

Apply these rules after the behavior is green:

  • Rename touched JavaScript source files from .js to .ts and touched React JavaScript files from .jsx to .tsx. The phrase “.tsx to .tsx” is interpreted as “.jsx to .tsx.” Update every affected import, export, test, route, and configuration reference.
  • Do not rename a runtime or tool configuration file when that tool cannot execute TypeScript. Record the concrete incompatibility in the implementation handoff instead of breaking the toolchain.
  • Add real TypeScript types during conversion. Do not silence errors with any, unsafe assertions, or blanket suppression comments.
  • Keep existing .ts and .tsx files in those extensions and improve their touched interfaces where the feature makes the type boundary clearer.
  • Define React component props with a named type, accept a single typed props parameter, and destructure inside the component body:
type ComponentAProps = {
  title: string;
};

const ComponentA = (props: ComponentAProps) => {
  const { title } = props;

  return <div>{title}</div>;
};
  • Apply the same pattern to touched components unless an existing framework-required signature makes it impossible. Do not introduce React.FC merely to type props.
  • Preserve behavior and public contracts. Run focused type checking, linting, formatting, and affected tests after renames and refactors.

Stage 3: Author compact Playwright acceptance coverage​

Run this stage only after the integrated implementation has passed the implement-feature QA and review gates.

Planner​

Delegate to playwright_test_planner with the approved Markdown specification, affected routes, authenticated seed requirements, and implementation handoff.

Require the Planner to:

  • Explore the implemented happy path and the important business flow in a real browser.
  • Run headlessly unless the human explicitly asks to watch headed execution.
  • Compare observed behavior with the approved specification; report drift instead of normalizing it.
  • Produce or update a readable Markdown test plan before executable tests are generated.
  • Record prerequisites, exact data ownership, mutation boundaries, and expected outcomes.
  • Avoid exhaustively permuting controls when representative coverage proves the same business rule.
  • Stop and ask the human when the approved specification does not determine an observed behavior; do not convert current UI behavior into a new requirement automatically.

Compact-flow rule​

Prefer one coherent business lifecycle per test. Use at most one or two acceptance tests for one feature or affected page unless the approved specification proves more are necessary.

Combine related interactions when they share setup and intent. For example, a listing journey may create or locate its record, then search, filter, apply advanced filters, paginate, open, edit, and verify it in one flow. Do not create one test per click or control.

Split a flow only when at least one of these applies:

  • different roles or authentication states require isolated contexts;
  • destructive or externally visible mutations need a separate safety boundary;
  • setup and teardown are materially independent;
  • failure isolation would otherwise make the test unsafe or impossible to recover;
  • the approved specification defines genuinely independent business outcomes.

Tests must not depend on execution order. When create and edit describe one lifecycle, carry the exact generated ID or URL through the same test. Otherwise seed each test independently through an approved public seam.

Plan conformance gate​

Compare the Planner's Markdown with the approved feature specification before generation.

  • If it only selects representative flows without changing expected behavior, continue.
  • If it adds, removes, weakens, or reinterprets expected behavior, stop for human approval and update the feature specification first.

AI may propose the plan; AI may not approve new expected behavior.

Generator​

After the conformance gate, delegate the approved plan to playwright_test_generator.

Require the Generator to:

  • Write the minimum one or two Playwright tests that express the planned business flow.
  • Use accessible, stable locators and test-owned unique data.
  • Mock only backend HTTP endpoints in a deterministic PR lane. Do not mock React hooks, contexts, services, or components.
  • Use a separately configured real-backend smoke lane when the repository supports it.
  • Keep mutations serial, set mutation retries to zero, and avoid cross-test leftovers.
  • Generate failure screenshots, videos, and traces for diagnosis. Add visual snapshots only when pixel appearance is an approved requirement.
  • Stop for human clarification when the approved plan leaves an expected outcome ambiguous; do not invent assertions.

If any required Playwright agent is unavailable, stop this stage and tell the human which agent definition is missing. Do not silently impersonate the missing agent.

Healer​

Delegate failures to playwright_test_healer and require evidence-first repair:

  1. Inspect the error, trace, screenshot, network evidence, and current specification.
  2. Classify the failure as test mechanics, test data/environment, specification drift, or product regression.
  3. Fix only proven locator, timing, fixture, isolation, or test-data defects automatically.
  4. Do not weaken assertions, skip/fixme tests, regenerate approved expectations, or change production behavior to make a test green without human review.
  5. Ask the human when classification or the correct expected behavior remains ambiguous after inspecting the evidence.
  6. Run the repaired test headlessly.
  7. Run the feature/page Playwright command.
  8. Run the repository's complete bun run playwright:test gate.
  9. Continue until all required gates pass or report a genuine external blocker with evidence.

Completion gate​

Declare the feature complete only when all of the following are true:

  • The human-approved Markdown specification is on disk and current.
  • Every behaviorally meaningful ambiguity discovered by any agent has a recorded human decision.
  • Every implement-feature hard-gate decision is satisfied or explicitly resolved by the human.
  • Touched source files complete the TypeScript and component-props refactor pass, with any toolchain exception documented.
  • Coordinated implementation, QA, code review, and integration gates pass.
  • The Playwright plan conforms to the approved behavior.
  • The important feature behavior is expressed as a compact one- or two-test flow unless a documented split criterion applies.
  • Focused, feature-level, and complete Playwright gates pass without hidden skips.
  • Failure artifacts remain diagnostic; snapshots exist only for approved visual requirements.
  • Durable feature references are updated and temporary coordination artifacts are removed.

End with a concise handoff listing the specification, implementation plan, generated tests, human decisions, commands run, and any remaining external blocker.