tdd-planner

TDD Planner

Generate high-quality, structured development plans following Test-Driven Development principles for use with the strict-loop command.

Quality Standard

Every plan must meet this checklist before saving:

• Context lists specific items to work on (not just "the feature")
• Success criteria are measurable (numbers, specific behaviors)
• Every task has a file path
• Code snippets show implementation structure
• Verification has expected output (PASS/FAIL + why)
• Self-correction is phase-specific, not generic
• Files to Modify table exists
• New Files to Create table exists
• Stuck handling is framework/task-specific

Reference: See references/good-example.md for expected quality.

Activation Triggers

This skill activates when:

• Planning a feature for iterative development
• Preparing prompts for strict-loop execution
• Breaking down complex tasks into TDD phases
• Creating structured development workflows

Core Principles

1. Specificity Over Vagueness — file paths, code snippets, measurable outcomes
2. Iteration Over Perfection — expect multiple passes, not first-draft solutions
3. Failures as Data — Red phase tests MUST fail first
4. Framework Awareness — use correct patterns for detected framework

Required Plan Sections

1. Context

## Context

- **Framework**: Flutter / Django / Next.js / etc.
- **Current State**: What exists now
- **Test Command**: `flutter test` / `pytest` / etc.
- **Lint Command**: `flutter analyze` / `ruff check .` / etc.
- **Items to Work On**:
  - `ComponentA` (description)
  - `ComponentB` (description)

2. Success Criteria (Measurable)

## Success Criteria

- [ ] Login returns JWT token (specific behavior)
- [ ] 81+ tests pass (quantitative)
- [ ] Invalid credentials return 401 (negative case)
- [ ] All tests pass (`flutter test`)
- [ ] Linter clean (`flutter analyze`)

3. File Tables (Required)

## Files to Modify

| File | Action |
|------|--------|
| `lib/main.dart` | Replace MultiProvider with ProviderScope |

## New Files to Create

| File | Purpose |
|------|---------|
| `lib/providers/auth_provider.dart` | Riverpod auth state |

4. Phases with Code Snippets

### Phase 2: Green - Implement Auth Provider

**Goal:** Create Riverpod provider that passes tests

**Tasks:**
- [ ] Create `lib/providers/auth_provider.dart`:
  - StateNotifierProvider with AuthNotifier
  - Methods: login(), logout(), checkAuth()

**Implementation Structure:**
\```dart
final authProvider = StateNotifierProvider<AuthNotifier, AuthState>((ref) {
  return AuthNotifier();
});
\```

**Verification:**
\```bash
flutter test test/providers/auth_test.dart
\```
**Expected:** Tests should PASS

**Self-correction:**
- If tests fail, check state class matches test expectations

5. Stuck Handling (Framework-Specific)

## Stuck Handling

### If same test keeps failing:
1. Read the exact error message
2. Check if ProviderScope wraps the widget tree
3. Verify ref.watch vs ref.read usage

### Alternative approaches if blocked:
1. Keep hybrid approach temporarily
2. Migrate one screen at a time

Framework Detection

Package manager auto-detection (defaults to bun):

• bun.lockb -> bun
• pnpm-lock.yaml -> pnpm
• yarn.lock -> yarn
• package-lock.json -> npm
• No lockfile -> bun (default)

Auto-detected frameworks (17+):

Category	Framework	Detection	Test	Lint
Mobile	Flutter	pubspec.yaml	flutter test	flutter analyze
	React Native	react-native in package.json	${PM} test	${PM} run lint
Python	Django	manage.py	pytest	ruff check .
	FastAPI	fastapi in pyproject.toml	pytest	ruff check .
	Flask	flask in pyproject.toml	pytest	ruff check .
Node.js	NestJS	@nestjs/core	${PM} test	${PM} run lint
	Next.js	next	${PM} test	${PM} run lint
	Nuxt.js	nuxt	${PM} test	${PM} run lint
	Hono	hono	bun test	bun run lint
	Express	express	${PM} test	${PM} run lint
	TanStack	@tanstack/react-router	bun test	bun run lint
Systems	Go	go.mod	go test ./...	golangci-lint run
	Rust	Cargo.toml	cargo test	cargo clippy
Web	Rails	rails in Gemfile	bundle exec rspec	bundle exec rubocop
	Laravel	laravel in composer.json	php artisan test	./vendor/bin/pint

Custom frameworks:

/strict-plan "Build API" --framework elixir --test-cmd "mix test" --lint-cmd "mix credo"

Phase Generation Rules

For New Features

1. Red: Write tests for the feature interface (expect FAIL)
2. Green: Implement minimum code to pass (include code snippet)
3. Refactor: Clean up, add types, documentation

For Bug Fixes

1. Red: Write test that reproduces the bug (should fail)
2. Green: Fix the bug (test passes)
3. Refactor: Ensure no regression, clean up

For Refactoring/Migration

1. Red: Ensure existing tests pass (baseline)
2. Green: Apply changes incrementally
3. Refactor: Verify tests still pass after each change

Task Detail Pattern

Bad Task:

- [ ] Create login view

Good Task:

- [ ] Create `lib/screens/login_screen.dart`:
  - ConsumerStatefulWidget
  - Form with email/password TextFormFields
  - Calls `ref.read(authProvider.notifier).login()`
  - Shows loading state during auth
  - Navigates to home on success

Anti-Patterns to Avoid

Don't	Do Instead
"Implement the feature"	"Create lib/auth/login.dart with ConsumerWidget"
"If it fails, try again"	"If tests pass in Red, they're too weak — add assertions"
Missing code snippets	Show actual structure with types and patterns
No file tables	Always list files to modify/create
"App works well"	"Login returns JWT, logout invalidates token, 401 on bad creds"
Generic stuck handling	Framework-specific: "Check ProviderScope wraps app"

Usage

Generate Plan

/strict-plan "Migrate to Riverpod" --framework flutter
/strict-plan "Add user authentication" --interactive

Execute Plan

/strict-loop --from-plan

References

• references/plan-template.md - Full template with all variables
• references/good-example.md - High-quality example plan
• references/framework-patterns.md - Framework-specific patterns