test-first-workflow

Files (10)

• SKILL.md
• .gitkeep · assets/
• .gitkeep · examples/
• quantity-field-plan.md · examples/
• .gitkeep · references/
• plan-to-test.md · references/
• .gitkeep · scripts/
• .gitkeep · templates/
• light-change-record.md · templates/
• task-checklist.md · templates/

SKILL.md (first lines)

# Test-First Workflow

Plan first, copy the completed plan into a checklist, and then use that checklist as the source of
truth for tests, implementation, and results.

## Choose the Change Tier

Before editing, pick one tier and size the process to the change. Use the disqualifier checklist in
[plan-to-test guidance](references/plan-to-test.md#change-tier-selection) to decide.

| Tier     | When                                                                                                                                                                                                                                              | Artifact                                                                                                                                                                                                                       |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| light    | A single configuration value, port number, dependency version bump, copy-only wording tweak, or documentation fix. No runtime behavior, contract, route, authorization, endpoint, or end-to-end test change, and one small cohesive set of edits. | No checklist file. Emit the attestation below and record the acceptance criteria, validation cases, and results in your response and the commit message body.                                                                  |
| standard | Anything that fails a light disqualifier: a behavior or branch change, a contract or schema change, a route or form change, authorization, a new endpoint or job or migration, or new behavior-locking tests.                                     | One `docs/checklists/<date>-<slug>.md` with the full `## Implementation Contract`, `## Missing-Case Review`, and `## Exact Test Cases`, exactly as described below.                                                            |
| large    | Two or more independently shippable behaviors, or work spanning multiple route groups, packages, or contracts.                                                                                                                                    | A parent checklist that declares `Tier: large` and links at least two child checklists under `## Child Checklists`. Each child is a standard-tier checklist with its own contract. Implement and validate one child at a time. |

Self-select the tier honestly. Any disqualifier answered "yes" forces standard tier; two or more
independently shippable behaviors force large tier. When unsure, choose the heavier tier.

Light tier creates no checklist file. Before the first edit, emit this block as visible text with
every answer filled in as `no`, then keep the acceptance criteria, validation cases, and recorded
results in your response and the commit body. The template
[light-change-record.md](templates/light-change-record.md) has the same block.

```
LIGHT-TIER-ATTESTATION
1. Changes runtime behavior, control flow, or a conditional branch: <yes or no>
2. Adds or changes an API contract, schema, DTO, validator, or shared type: <yes or no>
3. Changes a route, navigation, form behavior, or user-facing validation: <yes or no>
4. Touches authentication, authorization, sessions, roles, permissions, or ownership: <yes or no>
5. Adds or changes an endpoint, background job, scheduled task, or data migration: <yes or no>
6. Adds or modifies an e2e/integration/behavior test or any file under apps/playwright or apps/maestro: <yes or no>
7. Needs more than one small cohesive edit, or is really a large multi-behavior change: <yes or no>
Acceptance criteria: <1-3 lines>
Validation: <exact command(s) + expected result>
Recorded results: <command + observed result, filled after running>
```

Light-tier changes never invoke `e2e-regression-test-writer` or `maestro-mobile-e2e-test-writer`:
any end-to-end work, or any edit under `apps/playwright/**` or `apps/maestro/**`, is disqualifier
six and forces standard tier. Standard and large tiers are unchanged by this section and still
create checklist files and complete the Implementation Contract before editing.

## Plan Before the Checklist

Start every new task with a planning phase. Do not create the new checklist or change implementation
files until the plan covers the task context, small task breakdown, acceptance criteria, exact test
cases, implementation steps, dependencies, and risks.

1. Read the task request and the repository and package guidance that applies to it.
2. For a new bug, read relevant previous checklists first, including their updates, then inspect the
   implementations and tests they describe.
3. Identify the affected package, module, files, public behavior, user-visible acceptance criteria,
   dependencies, constraints, and non-goals.
4. Find the real rules in the request, schemas, validators, types, existing tests, current code, and
   documentation.
5. Locate relevant test files, test helpers, build scripts, sample data, and system boundaries.
6. Split the work into small parts and plan exact test or validation cases as described below.
7. Load `checklist-tracking` before creating the checklist and follow its nesting, status, matching,
   cross-reference, and history rules.
8. Create an `## Implementation Contract` in the checklist before editing. It must contain `### Feature
Boundaries`, `### Route-Group Ownership`, `### User Journey`, `### Complete Test Matrix`, and
   `### Unresolved Conflicts`. The matrix must map every reachable happy and non-happy path to its own
   test ID or explicit limitation; conflicts must name the winning rule or the blocking question.

## Split the Work Until Each Part Is Small

Do not treat a feature name, screen name, endpoint name, or broad implementation step as a ready task.

1. Start with the requested outcome.
2. Split it into separate behaviors that a user or another system can notice.
3. Split each behavior into its separate rules, choices, success paths, failure paths, and state
   changes.
4. Keep splitting with as many checklist levels as needed.
5. Stop only when the smallest item has one clear result and can be tested on its own.

Split an item again if it contains two things that could pass or fail separately. Words such as
"and," "or," "all validations," "handle errors," or "add tests" often show that an item is still too
broad. A parent item is only a summary; its smaller child items define the real work.

Repeat this breakdown when repository discovery reveals another rule, choice, state, or failure path.

Use plain English for task items, test cases, expected results, required changes, forbidden work,
reasons, and questions. If a technical term is unavoidable, explain it in simple words the first time
it appears.

## Plan One Exact Test Situation at a Time

Plan exact test or validation cases for every smallest task item before writing tests or changing
implementation files. A heading such as "test validation," "add focused tests," "test edge cases," or
"test errors" is not a test case.

## Exact Test Case Rules

Every case must contain these fields: `Small task:`, `Source:`, `Test place:`, `Starting state:`,
`Exact input or fixture:`, `Interaction steps:`, `Main behavior:`, `Expected result:`, `Must change:`,
`Must not happen:`, `Planned command:`, `Expected result before the code change:`,
`First observed run:`, and `Passing rerun:`.

During planning, fill in `Planned command:` and `Expected result before the code change:`. Fill in
`First observed run:` only after its command has run. Fill in `Passing rerun:` only after its command
has run. Do not invent test results before running the command.

If trusted sources disagree, check which source wins under repository guidance. If no rule answers
that question, record the conflict, ask the user, and block the affected tests and implementation.

Give every case a `TEST-<AREA>-<NUMBER>` ID and use these fields:

- **Small task:** The smallest task item it proves.
- **Source:** The request, schema, validator, existing test, current public behavior, or other rule.
- **Test place:** The test kind and file where it belongs.
- **Starting state:** The exact state and sample data before the test.
- **Exact input or fixture:** The exact input or sample data.
- **Interaction steps:** Every step needed, such as enter a value and then submit.
- **Main behavior:** The one behavior or result being checked.
- **Expected result:** The exact visible result, returned value, error, status, or state.
- **Must change:** Data, calls, events, or files that must change, when relevant.
- **Must not happen:** Work that must not happen after rejection or failure, when relevant.
- **Planned command:** The command to run after the checklist exists.

From gowebknot/monorepo-template, MIT.

More from gowebknot/monorepo-template