From 39a34e46db6a39f5a0af405b6606e413a3c1ed1d Mon Sep 17 00:00:00 2001 From: Toni Doni Date: Wed, 25 Mar 2026 01:42:45 +0300 Subject: [PATCH 1/6] docs: tighten tdd workflow red-green validation --- skills/tdd-workflow/SKILL.md | 45 ++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/skills/tdd-workflow/SKILL.md b/skills/tdd-workflow/SKILL.md index 90c0a6df..10c81f1e 100644 --- a/skills/tdd-workflow/SKILL.md +++ b/skills/tdd-workflow/SKILL.md @@ -47,6 +47,16 @@ ALWAYS write tests first, then implement code to make tests pass. - Browser automation - UI interactions +### 4. Git Checkpoints +- If the repository is under Git, create a checkpoint commit after each TDD stage +- Do not squash or rewrite these checkpoint commits until the workflow is complete +- Each checkpoint commit message must describe the stage and the exact evidence captured +- The preferred compact workflow is: + - one commit for failing test added and RED validated + - one commit for minimal fix applied and GREEN validated + - one optional commit for refactor complete +- Separate evidence-only commits are not required if the test commit clearly corresponds to RED and the fix commit clearly corresponds to GREEN + ## TDD Workflow Steps ### Step 1: Write User Journeys @@ -87,6 +97,25 @@ npm test # Tests should fail - we haven't implemented yet ``` +This step is mandatory and is the RED gate for all production changes. + +Before modifying business logic or other production code, you must verify all of the following: +- The relevant test target compiles successfully +- The new or changed test is actually executed +- The result is RED +- The failure is caused by the intended business-logic bug, undefined behavior, or missing implementation +- A compile-time RED is valid if the new test newly instantiates, references, or exercises the buggy code path and exposes the intended defect +- The failure is not caused only by unrelated syntax errors, broken test setup, missing dependencies, or unrelated regressions + +A test that was only written but not compiled and executed does not count as RED. + +Do not edit production code until this RED state is confirmed. + +If the repository is under Git, create a checkpoint commit immediately after this stage is validated. +Recommended commit message format: +- `test: add reproducer for ` +- This commit may also serve as the RED validation checkpoint if the reproducer was compiled and executed and failed for the intended reason + ### Step 4: Implement Code Write minimal code to make tests pass: @@ -97,12 +126,24 @@ export async function searchMarkets(query: string) { } ``` +If the repository is under Git, create a checkpoint commit immediately after the minimal fix is in place. +Recommended commit message format: +- `fix: minimal fix for ` + ### Step 5: Run Tests Again ```bash npm test # Tests should now pass ``` +Rerun the same relevant test target after the fix and confirm the previously failing test is now GREEN. + +Only after a valid GREEN result may you proceed to refactor. + +If the repository is under Git, create a checkpoint commit immediately after GREEN is validated. +Recommended commit message format: +- The fix commit may also serve as the GREEN validation checkpoint if the same relevant test target was rerun and passed + ### Step 6: Refactor Improve code quality while keeping tests green: - Remove duplication @@ -110,6 +151,10 @@ Improve code quality while keeping tests green: - Optimize performance - Enhance readability +If the repository is under Git, create a checkpoint commit immediately after refactoring is complete and tests remain green. +Recommended commit message format: +- `refactor: clean up after fix` + ### Step 7: Verify Coverage ```bash npm run test:coverage From 46f6e3644b8116e48a0752326f733086025bd179 Mon Sep 17 00:00:00 2001 From: ToniDonDoni Date: Wed, 25 Mar 2026 02:07:53 +0300 Subject: [PATCH 2/6] Apply suggestions from code review Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> --- skills/tdd-workflow/SKILL.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/skills/tdd-workflow/SKILL.md b/skills/tdd-workflow/SKILL.md index 10c81f1e..e1027461 100644 --- a/skills/tdd-workflow/SKILL.md +++ b/skills/tdd-workflow/SKILL.md @@ -100,7 +100,7 @@ npm test This step is mandatory and is the RED gate for all production changes. Before modifying business logic or other production code, you must verify all of the following: -- The relevant test target compiles successfully +- The relevant test target compiles successfully, or the compile failure is itself the RED signal (i.e., the new test instantiates the buggy code path and a compile-time RED is the intended failure) - The new or changed test is actually executed - The result is RED - The failure is caused by the intended business-logic bug, undefined behavior, or missing implementation @@ -126,9 +126,7 @@ export async function searchMarkets(query: string) { } ``` -If the repository is under Git, create a checkpoint commit immediately after the minimal fix is in place. -Recommended commit message format: -- `fix: minimal fix for ` +If the repository is under Git, stage the minimal fix now but defer the checkpoint commit until GREEN is validated in Step 5. ### Step 5: Run Tests Again ```bash From 3c59d8dc60ce8cb4c7ad66e3e732ead16c837e50 Mon Sep 17 00:00:00 2001 From: Toni Doni Date: Wed, 25 Mar 2026 02:10:01 +0300 Subject: [PATCH 3/6] adjust: clarify runtime vs compile-time red validation --- skills/tdd-workflow/SKILL.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/skills/tdd-workflow/SKILL.md b/skills/tdd-workflow/SKILL.md index e1027461..40363722 100644 --- a/skills/tdd-workflow/SKILL.md +++ b/skills/tdd-workflow/SKILL.md @@ -99,12 +99,15 @@ npm test This step is mandatory and is the RED gate for all production changes. -Before modifying business logic or other production code, you must verify all of the following: -- The relevant test target compiles successfully, or the compile failure is itself the RED signal (i.e., the new test instantiates the buggy code path and a compile-time RED is the intended failure) -- The new or changed test is actually executed -- The result is RED -- The failure is caused by the intended business-logic bug, undefined behavior, or missing implementation -- A compile-time RED is valid if the new test newly instantiates, references, or exercises the buggy code path and exposes the intended defect +Before modifying business logic or other production code, you must verify a valid RED state via one of these paths: +- Runtime RED: + - The relevant test target compiles successfully + - The new or changed test is actually executed + - The result is RED +- Compile-time RED: + - The new test newly instantiates, references, or exercises the buggy code path + - The compile failure is itself the intended RED signal +- In either case, the failure is caused by the intended business-logic bug, undefined behavior, or missing implementation - The failure is not caused only by unrelated syntax errors, broken test setup, missing dependencies, or unrelated regressions A test that was only written but not compiled and executed does not count as RED. From a61947bb5c101dad2fe9ae570260e710cb1d633e Mon Sep 17 00:00:00 2001 From: Toni Doni Date: Wed, 25 Mar 2026 02:14:39 +0300 Subject: [PATCH 4/6] adjust: generalize refactor commit placeholder --- skills/tdd-workflow/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/tdd-workflow/SKILL.md b/skills/tdd-workflow/SKILL.md index 40363722..fc15c2ac 100644 --- a/skills/tdd-workflow/SKILL.md +++ b/skills/tdd-workflow/SKILL.md @@ -154,7 +154,7 @@ Improve code quality while keeping tests green: If the repository is under Git, create a checkpoint commit immediately after refactoring is complete and tests remain green. Recommended commit message format: -- `refactor: clean up after fix` +- `refactor: clean up after implementation` ### Step 7: Verify Coverage ```bash From fee93f2dabbbef8e3ba8f845475a89a1da2ebb76 Mon Sep 17 00:00:00 2001 From: ToniDonDoni Date: Wed, 25 Mar 2026 02:19:09 +0300 Subject: [PATCH 5/6] Apply suggestions from code review Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> --- skills/tdd-workflow/SKILL.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/skills/tdd-workflow/SKILL.md b/skills/tdd-workflow/SKILL.md index fc15c2ac..1db39066 100644 --- a/skills/tdd-workflow/SKILL.md +++ b/skills/tdd-workflow/SKILL.md @@ -116,7 +116,7 @@ Do not edit production code until this RED state is confirmed. If the repository is under Git, create a checkpoint commit immediately after this stage is validated. Recommended commit message format: -- `test: add reproducer for ` +- `test: add reproducer for ` - This commit may also serve as the RED validation checkpoint if the reproducer was compiled and executed and failed for the intended reason ### Step 4: Implement Code @@ -143,6 +143,7 @@ Only after a valid GREEN result may you proceed to refactor. If the repository is under Git, create a checkpoint commit immediately after GREEN is validated. Recommended commit message format: +- `fix: ` - The fix commit may also serve as the GREEN validation checkpoint if the same relevant test target was rerun and passed ### Step 6: Refactor From 9cc5d085e13b31a07d5c95a7ba31ba8174f648f0 Mon Sep 17 00:00:00 2001 From: Toni Doni Date: Wed, 25 Mar 2026 14:09:59 +0300 Subject: [PATCH 6/6] adjust: scope tdd checkpoints to active branch --- skills/tdd-workflow/SKILL.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/skills/tdd-workflow/SKILL.md b/skills/tdd-workflow/SKILL.md index 1db39066..c8e5d06f 100644 --- a/skills/tdd-workflow/SKILL.md +++ b/skills/tdd-workflow/SKILL.md @@ -51,6 +51,9 @@ ALWAYS write tests first, then implement code to make tests pass. - If the repository is under Git, create a checkpoint commit after each TDD stage - Do not squash or rewrite these checkpoint commits until the workflow is complete - Each checkpoint commit message must describe the stage and the exact evidence captured +- Count only commits created on the current active branch for the current task +- Do not treat commits from other branches, earlier unrelated work, or distant branch history as valid checkpoint evidence +- Before treating a checkpoint as satisfied, verify that the commit is reachable from the current `HEAD` on the active branch and belongs to the current task sequence - The preferred compact workflow is: - one commit for failing test added and RED validated - one commit for minimal fix applied and GREEN validated @@ -118,6 +121,7 @@ If the repository is under Git, create a checkpoint commit immediately after thi Recommended commit message format: - `test: add reproducer for ` - This commit may also serve as the RED validation checkpoint if the reproducer was compiled and executed and failed for the intended reason +- Verify that this checkpoint commit is on the current active branch before continuing ### Step 4: Implement Code Write minimal code to make tests pass: @@ -145,6 +149,7 @@ If the repository is under Git, create a checkpoint commit immediately after GRE Recommended commit message format: - `fix: ` - The fix commit may also serve as the GREEN validation checkpoint if the same relevant test target was rerun and passed +- Verify that this checkpoint commit is on the current active branch before continuing ### Step 6: Refactor Improve code quality while keeping tests green: @@ -156,6 +161,7 @@ Improve code quality while keeping tests green: If the repository is under Git, create a checkpoint commit immediately after refactoring is complete and tests remain green. Recommended commit message format: - `refactor: clean up after implementation` +- Verify that this checkpoint commit is on the current active branch before considering the TDD cycle complete ### Step 7: Verify Coverage ```bash