spec-kitty / spec-kitty/spec-kitty
Doctrine: sharpen test-first guidance with Matt Pocock TDD tracer-bullet rules
- 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
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