# 1. RED: write a failing test
pnpm --filter <pkg> test:run     # must FAIL

# 2. GREEN: minimal code to pass
pnpm --filter <pkg> test:run     # must PASS

# 3. REFACTOR: clean up
pnpm --filter <pkg> test:run     # must STAY PASS

// ❌ REJECTED
const data: any = getData();

// ✅ Library types
import type { GeoJSONSource } from 'mapbox-gl';
const source = map.getSource('points') as GeoJSONSource;

// ✅ Database types (source of truth for DB shape)
import type { Database } from '~/lib/database.types';
type ProjectRow = Database['public']['Tables']['projects']['Row'];

// ✅ unknown + type guards
function process(data: unknown) {
  if (typeof data === 'object' && data !== null) { /* ... */ }
}

// ❌ REJECTED
const url = 'http://localhost:3000/auth/callback';
const origin = window.location.origin;

// ✅ CORRECT
const url = process.env.NEXT_PUBLIC_APP_URL + '/auth/callback';

pnpm typecheck                     # exit 0
pnpm lint:fix                      # exit 0
pnpm format:fix                    # no diff (or commit it)
pnpm --filter <pkg> test:run       # all green
pnpm --filter <app> build          # exit 0 (when applicable)

Intent → (Spec) → Investigation → TDD (RED) → Build (GREEN/REFACTOR) → Review → Docs → Ship

## Investigation Report

**Task:** <one sentence>

**Searched:**
- packages/gw/   → grep "<term>"     → <findings or "no matches">
- packages/fw/   → grep "<term>"     → <findings or "no matches">
- apps/web/      → grep "<term>"     → <findings or "no matches">
- .kiro/specs/   → ls + grep         → <relevant specs or "none">
- .kiro/steering → relevant files    → <list>

**What already exists that I will reuse:**
- <file:line> — <what it provides>

**What does not exist and must be created:**
- <component/service/page> in `packages/gw/<name>/` because <reason>

**Decision:**
- Reuse: <list>
- Create new in @gw: <list>
- Migrate from @fw if encountered: <list>

[ ] Investigation Report included in the plan       (Law 1)
[ ] Failing test was written first                  (Law 2)
[ ] Implementation makes the test pass
[ ] All new code is in @gw/* or app workspaces      (Law 8)
[ ] No new files in @fw/* or @kit/*                 (Law 8)
[ ] pnpm typecheck                                  → exit 0
[ ] pnpm lint:fix                                   → exit 0
[ ] pnpm format:fix                                 → no uncommitted diff
[ ] pnpm --filter <pkg> test:run                    → all green
[ ] pnpm --filter <app> build                       → exit 0 (if app code changed)
[ ] Feature manually verified in browser            → no console errors
[ ] No regressions in adjacent features
[ ] i18n keys present in en, pt-br, ar              → if UI strings added
[ ] RTL verified                                    → if UI changed
[ ] RLS policy added/updated and tested             → if DB tables touched
[ ] docs/features/{FEATURE}.md updated              → §Documentation Contract
[ ] apps/docs MDX updated                           → if user-facing
[ ] ADR written                                     → if architectural decision made
[ ] Commit message proposed (NOT executed)          → Law 4

type(scope): brief description

[Optional body explaining the why]

✅ Verified:
- TypeCheck: ✅
- Lint: ✅
- Tests: ✅ <X/Y passing>
- Build: ✅
- Manual: ✅

📚 Documentation:
- docs/features/{FEATURE}.md
- apps/docs/content/docs/{section}/{feature}.mdx (if user-facing)
- docs/architecture/ADR-NNN-{slug}.md (if architectural decision)

Closes #XXX

# Track lifecycle (optional)
pnpm track:list
pnpm track:create my-track "Agent name" "What this track is for"
pnpm track:switch my-track
pnpm context:restart

# Save / load context
pnpm context:save
pnpm context:load