The Three Acts

The Fireskills methodology organizes all engineering work into Three Acts. Each Act represents a distinct mindset, toolset, and validation threshold, ensuring that implementation never begins without clear requirements and proven test contracts.

┌──────────────────────────────────────┐
│            ACT I: DEFINE             │
│ • User Stories (US)                  │
│ • Requirements (FR/NFR)              │
│ • Gherkin BDD Scenarios              │
│ ──> Definition Gate: Passed          │
└──────────────────┬───────────────────┘
                   │
                   ▼
┌──────────────────────────────────────┐
│        ACT II: DESIGN & PROVE        │
│ • Task Decomposition & 6-Step List   │
│ • Executable TDD Tests               │
│ • Observed RED State                 │
│ ──> Plan Gate: Passed                │
└──────────────────┬───────────────────┘
                   │
                   ▼
┌──────────────────────────────────────┐
│           ACT III: DELIVER           │
│ • RED -> GREEN Implementation        │
│ • Visual Inspection against Tokens   │
│ • Full Regression & Documentator     │
│ ──> Delivery Gate: Passed            │
└──────────────────────────────────────┘

Act I: Define

Objective: Establish what must be built, why it matters, who it serves, and what criteria define success.

Activities:

• Intake & Scope Clarification: Ingest raw requests from specs/inbox/ into specs/backlog/.
• Stakeholder Discovery: Conduct structured inquiry via the Numbered Question Contract to resolve ambiguities and edge cases.
• Specification Authoring: Document User Stories (US), Functional Requirements (FR), and Non-Functional Requirements (NFR).
• Gherkin BDD Scenarios: Formulate human-readable behavior specifications (Given / When / Then) directly in spec.md.
• UI & Data Discovery: Specify affected screens, inputs, error states, and schema modifications.

Exit Threshold:

Act I concludes only when the Definition Gate is formally marked as Passed.

Act II: Design & Prove

Objective: Formulate the technical battle plan and prove that our understanding is correct by establishing failing tests (RED) before writing any application code.

Activities:

• Task Decomposition: Divide the spec into atomic, sequenced tasks within spec.md. Each task must follow the mandatory 6-step checklist (PREP, EXECUTE, VERIFY, VISUAL, EVIDENCE, IMPROVE).
• Architectural Alignment: Select the appropriate technical patterns, ensuring compatibility with Cloudflare Workers constraints.
• TDD Test Derivation: Derive executable Vitest test suites directly from the reference Gherkin scenarios. Every executable case carries its own // SPECSFY: marker.
• Valid RED Observation: Run the test suite (bun run test) and observe that tests fail strictly because functionality is not yet implemented, not due to syntax or environmental errors.

Exit Threshold:

Act II concludes only when the Plan Gate is formally marked as Passed.

Act III: Deliver

Objective: Implement production-grade code, achieve passing tests (GREEN), conduct visual reviews, and package verified proof.

Activities:

• RED → GREEN → REFACTOR: Write minimal, clean code to turn failing tests green. Refactor for clarity, performance, and adherence to stack patterns.
• Visual Design Verification: Inspect rendered interfaces across desktop and mobile viewports against .fireskills/DESIGNSYSTEM.MD, verifying typography, spacing, padding, borders, and accessibility.
• Regression Suite: Execute full test suites and typecheckers (tests from the root; types from apps/app):
  bun run test                       # repository root
  cd apps/app
  bun run typecheck
  bunx vue-tsc --noEmit -p server/tsconfig.json
  

• Context & Documentation Sync: Update .fireskills context files (DATABASE.md, INTERFACE.md) and run fireskill-documentator.

Exit Threshold:

Act III concludes only when the Delivery Gate is formally marked as Passed and the specification is transitioned to completed.

Reopening Acts on Requirement Drift

If requirements change mid-cycle, downstream gates cannot remain valid:

• Requirement or Behavioral Change: Reopens Acts I, II, and III. The Definition Gate and Plan Gate reset to Pending.
• Technical Plan Change: Reopens Acts II and III. The Definition Gate remains Passed, while the Plan Gate resets to Pending.