• Maximum 20 lines per function - if longer, decompose IMMEDIATELY
• Maximum 3 parameters per function - if more, use an options object or decompose
• Maximum 2 levels of nesting - flatten with early returns or extract functions
• Single responsibility - each function does exactly one thing
• Descriptive names over comments - if you need a comment to explain what, rename it

• Maximum 200 lines per file - if longer, split by responsibility BEFORE continuing
• Maximum 10 functions per file - keeps cognitive load manageable
• One export focus per file - a file should have one primary purpose

• Maximum 3 levels of directory nesting - flat is better than nested
• Clear boundaries - each module has a single public interface
• No circular dependencies - ever

1. Count total lines - if > 200, STOP and split
2. Count functions - if > 10, STOP and split
3. Check each function length - if any > 20 lines, STOP and decompose
4. Check parameter counts - if any > 3, STOP and refactor

⚠️ FILE SIZE VIOLATION DETECTED

[filename] has [X] lines (limit: 200)

Splitting into:
- [filename-a].ts - [responsibility A]
- [filename-b].ts - [responsibility B]

• Pure functions for business logic - no side effects, deterministic
• Side effects only at boundaries - API calls, database, file system at edges
• Data in, data out - functions transform data, they don't mutate state

• No inheritance deeper than 1 level - prefer interfaces/composition
• Small, composable utilities - build complex from simple
• Dependency injection - pass dependencies, don't import them directly

• Fail fast, fail loud - errors surface immediately
• No silent failures - every error is logged or thrown
• Design APIs where misuse is impossible

• 100% coverage on business logic - the functional core
• Integration tests for boundaries - API endpoints, database operations
• No untested code merges - CI blocks without passing tests
• Test behavior, not implementation - tests survive refactoring
• Each test runs in isolation - no interdependence

• ❌ Global state
• ❌ Magic numbers/strings - use named constants
• ❌ Deep nesting - flatten or extract
• ❌ Long parameter lists - use objects
• ❌ Comments explaining "what" - code should be self-documenting
• ❌ Dead code - delete it, git remembers
• ❌ Copy-paste duplication - extract to shared function
• ❌ God objects/files - split by responsibility
• ❌ Circular dependencies
• ❌ Premature optimization
• ❌ Large PRs - small, focused changes only
• ❌ Mixing refactoring with features - separate commits

• Criterion 1 - specific, measurable
• Criterion 2 - specific, measurable

• Manual: [steps to manually test]
• Automated: [test file/command that validates this]

• Depends on: [TODO-xxx] (if any)
• Blocks: [TODO-yyy] (if any)

1. Atomic - Each todo is a single, completable unit of work
2. Testable - Every todo has validation criteria and test cases
3. Sized - If larger than "M", break it down further
4. Independent - Minimize dependencies between todos
5. Tracked - Move between active.md → completed.md when done

• ❌ Tests were not written first (skipped RED phase)
• ❌ Tests did not fail initially (invalid tests)
• ❌ Any test is failing
• ❌ Linter has errors (warnings may be acceptable)
• ❌ Type checker has errors
• ❌ Coverage dropped below threshold

undefined

1. Step one
2. Step two
3. Observe: [incorrect behavior]
4. Expected: [correct behavior]

• Existing test coverage: [list relevant test files]
• Gap identified: [what the tests missed]
• New test needed: [describe the test to add]

• ❌ Fixing without a test - Bug will likely return
• ❌ Writing test after fix - Can't prove test catches the bug
• ❌ Skipping test gap analysis - Misses why tests didn't catch it
• ❌ Only testing the fix - Must run full test suite for regressions

• Email field shows error for invalid format
• Error clears when user fixes the email
• Form cannot submit with invalid email
• Valid emails pass through without error

• Manual: Enter "notanemail" in signup form, verify error appears
• Automated:

  npm test -- --grep "email validation"

• Depends on: [TODO-041] Signup form component
• Blocks: [TODO-045] Signup flow integration test

1. No secrets in code - Use environment variables, never commit secrets

2. .env

   in

   .gitignore

   - Always, no exceptions
3. No secrets in client-exposed env vars - Never use

   VITE_*

   ,

   NEXT_PUBLIC_*

   for secrets
4. Validate all input - Use Zod/Pydantic at API boundaries
5. Parameterized queries only - No string concatenation for SQL
6. Hash passwords properly - bcrypt with 12+ rounds
7. Dependency scanning - npm audit / safety check must pass

• .gitignore

  with secrets patterns

• .env.example

  with all required vars (no values)

• scripts/security-check.sh

  for pre-commit validation

• Secret scanning (detect-secrets / trufflehog)
• Dependency audit (npm audit / safety)
• Static analysis (CodeQL)

• Minimum 80% code coverage - CI must fail below this
• Business logic (core/) should aim for 100%
• Integration tests cover boundaries

1. Linting (auto-fix where possible)
2. Type checking
3. Tests (at minimum, affected tests)

1. Decision made? → Log to

   _project_specs/session/decisions.md

2. >10 tool calls? → Full checkpoint to

   current-state.md

3. Major feature done? → Archive to

   session/archive/

4. Otherwise → Quick update to

   current-state.md

1. Read

   _project_specs/session/current-state.md

2. Check

   _project_specs/todos/active.md

3. Continue from documented "Next Steps"

1. Archive current session
2. Update

   current-state.md

   with handoff notes
3. Ensure next steps are specific and actionable

1. Clarify requirements if ambiguous
2. Propose structure - outline before code
3. Write tests FIRST - based on test cases table (RED phase)
4. Run tests to verify they fail - proves tests are valid
5. Implement minimum code to make tests pass (GREEN phase)
6. Run full validation - lint, typecheck, coverage (VALIDATE phase)
7. Flag complexity - warn if approaching limits
8. Checkpoint after completing - update session state, log TDD execution

• "Add email validation"
• "Fix the login bug"
• "Build a REST API for todos"
• "Refactor the auth module"

1. Extract requirements from the request
2. Define completion criteria (tests passing, lint clean, etc.)
3. Structure as Ralph prompt with TDD workflow
4. Invoke

   /ralph-loop

   with appropriate

   --max-iterations

   and

   --completion-promise

"Add a forgot password feature"

/ralph-loop "

• User can request password reset via email
• Reset link sent to registered email
• Link expires after 24 hours
• User can set new password via link

1. Write failing tests for each requirement
2. Verify tests FAIL (RED)
3. Implement feature
4. Verify tests PASS (GREEN)
5. Run lint + typecheck
6. Repeat if failures

• All tests passing
• Coverage >= 80%
• Lint clean
• Security review (no token in URL params, etc.)

• "Just explain..." (explanation only)
• "Quick fix for..." (one-liner)
• "Don't loop..." (explicit opt-out)
• "Help me understand..." (learning/discussion)