spec-kitty / spec-kitty/spec-kitty

Doctrine: sharpen test-first guidance with Matt Pocock TDD tracer-bullet rules

Open
#1,277 1 comment 1 reaction 0 assignees View on GitHub
deferred doctrine enhancement priority:P3
Dominant language
Python
Stars
1.6k
Forks
165
Avg merge
13h 53m
Merged PRs (30d)
336

Description

## Recommendation

Use the current `mattpocock/skills` TDD skill to sharpen Spec Kitty's existing test-first Doctrine rather than adding a separate competing workflow.

Spec Kitty already has `DIRECTIVE_034`, `tdd-red-green-refactor`, bug-fixing tactics, and test quality gates. The value here is importing the stronger operational language around tracer bullets, vertical test cycles, public-interface behavior tests, and avoiding horizontal test batches.

## Source materials

Upstream snapshot reviewed: https://github.com/mattpocock/skills/tree/b8be62ffacb0118fa3eaa29a0923c87c8c11985c

Relevant files:

- `tdd` skill: https://github.com/mattpocock/skills/blob/b8be62ffacb0118fa3eaa29a0923c87c8c11985c/skills/engineering/tdd/SKILL.md
- Test examples: https://github.com/mattpocock/skills/blob/b8be62ffacb0118fa3eaa29a0923c87c8c11985c/skills/engineering/tdd/tests.md
- Mocking guidance: https://github.com/mattpocock/skills/blob/b8be62ffacb0118fa3eaa29a0923c87c8c11985c/skills/engineering/tdd/mocking.md
- Interface design: https://github.com/mattpocock/skills/blob/b8be62ffacb0118fa3eaa29a0923c87c8c11985c/skills/engineering/tdd/interface-design.md
- Deep modules: https://github.com/mattpocock/skills/blob/b8be62ffacb0118fa3eaa29a0923c87c8c11985c/skills/engineering/tdd/deep-modules.md
- Refactoring phase: https://github.com/mattpocock/skills/blob/b8be62ffacb0118fa3eaa29a0923c87c8c11985c/skills/engineering/tdd/refactoring.md

Existing Spec Kitty Doctrine to review/update:

- `src/doctrine/directives/built-in/034-test-first-development.directive.yaml`
- `src/doctrine/tactics/built-in/testing/tdd-red-green-refactor.tactic.yaml`
- `src/doctrine/tactics/built-in/testing/test-boundaries-by-responsibility.tactic.yaml`
- `src/doctrine/tactics/built-in/testing/function-over-form-testing.tactic.yaml`
- `src/doctrine/styleguides/built-in/testing-principles.styleguide.yaml`

## Specific import ideas

- Add an anti-pattern for horizontal slicing: do not write all tests first and then all implementation.
- Emphasize one behavior -> one failing test -> minimal implementation -> repeat.
- Strengthen the rule that tests verify behavior through public interfaces, not implementation structure.
- Connect test design to module/interface design: the interface is the test surface.
- Treat the refactor phase as a separate green-only phase, with tests run after each meaningful step.

## Attribution

Do not forget attribution. If adapted, cite `mattpocock/skills`, commit `b8be62ffacb0118fa3eaa29a0923c87c8c11985c`, and the upstream TDD files above in artifact notes or graph comments.

Contributor guide

Open the contributing guide

Research direction

Review the listed Doctrine files, starting with src/doctrine/directives/built-in/034-test-first-development.directive.yaml and tdd-red-green-refactor.tactic.yaml, alongside the cited upstream TDD files. Update the existing guidance with tracer bullets, vertical red-green-refactor cycles, public-interface testing, and the horizontal-slicing anti-pattern; preserve attribution to the specified commit and upstream files.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.