Phase 1: Run All Unit Tests

Run the full unit test suite first. Stop if tests fail.

npm run test:unit -- --run

If failures are in changed files, fix them. If failures are pre-existing/unrelated, inform user and ask how to proceed.

Phase 2: Identify Relevant E2E Tests

1. Get changed files:

git diff --name-only HEAD

2. Map changed files to E2E tests using these rules:

3. List the relevant E2E tests found. If none are relevant, skip to Phase 4.

Phase 3: Run and Fix Relevant E2E Tests

Run only the relevant E2E tests identified in Phase 2:

npx playwright test <spec-file> --retries=3 --timeout=120000

If E2E fails due to our changes:

1. Read the failing test to understand what it expects
2. Fix either the code or the test as appropriate
3. Re-run until pass

If E2E fails due to pre-existing issues:

1. Inform user of unrelated failure
2. Ask whether to skip or fix

Phase 4: Evaluate Coverage Needs

Assess if new tests are needed for the changed files.

1. Identify changed testable files (.ts, .tsx in src/, excluding tests)

2. For each file, check:

   • Does a corresponding test file exist?
   • Does the test cover the changed functionality?

3. Use AskUserQuestion if gaps exist:

{
  questions: [
    {
      question: "Found coverage gaps. Create tests for these files?",
      header: "Coverage",
      options: [
        {
          label: "Yes, create tests",
          description: "Write missing unit/E2E tests",
        },
        { label: "Skip for now", description: "Commit without new tests" },
      ],
      multiSelect: false,
    },
  ];
}

Phase 5: Write New Tests (If Needed)

If user approves, create tests following these patterns:

Follow patterns in:

• claude-patterns/testing-patterns.md (unit tests)
• claude-patterns/playwright-best-practices.md (E2E tests)

Run new tests to verify they pass before continuing.

Phase 6: Lint and Fix Errors

Lint all changed files:

git diff --name-only HEAD | grep -E '\.(ts|tsx)$' | xargs npx eslint --max-warnings 0

# Auto-fix what's possible
git diff --name-only HEAD | grep -E '\.(ts|tsx)$' | xargs npx eslint --fix

Phase 7: Sync Documentation

Check if code changes affect documentation in .claude/rules/ and claude-patterns/.

1. Get changed source files:

git diff --name-only HEAD | grep -E '\.(ts|tsx)$'

2. Search documentation for references to changed files:

# For each changed file, search with multiple patterns
grep -rE "(src/path/to/file\.ts|filename\.ts)" claude-patterns/ .claude/rules/

3. For each doc file with references to changed code:

   • Read the doc to understand context (not blind find/replace)
   • Verify the reference: Does the file/function still exist?
   • Identify staleness: Has the path, name, or behavior changed?

4. Categorize updates needed:

5. If updates needed, use AskUserQuestion:

{
  questions: [
    {
      question: "Found stale documentation references. How to proceed?",
      header: "Doc Sync",
      options: [
        {
          label: "Update docs",
          description: "Apply context-aware updates, include in commit",
        },
        {
          label: "Review each",
          description: "Show me each change before applying",
        },
        { label: "Skip", description: "Commit code without doc updates" },
      ],
      multiSelect: false,
    },
  ];
}

Known Limitations:

• May miss relative paths or partial filename matches
• Line number references become stale on any file edit
• Cannot detect semantic/behavior changes, only structural (renames, deletions)

Phase 8: Commit

1. Stage changed files:

git add <files>

2. Commit with descriptive message:

git commit -m "$(cat <<'EOF'
<type>(<scope>): <description>

<body>

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
EOF
)"