Phase	Action	Gate
1	Run all unit tests	Must pass
2	Identify relevant E2E tests	Based on changes
3	Fix failing E2Es, run relevant only	Must pass
4	Evaluate coverage needs	Ask user
5	Write new tests if needed	Optional
6	Lint and fix errors	Must pass
7	Sync documentation	User approval
8	Commit changes	Only if all pass

Track progress with TodoWrite.

Phase 1: Run All Unit Tests

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

npm run test:unit -- --run

Result	Action
All pass	Continue to Phase 2
Failures	Fix failing tests, re-run until pass

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

Get changed files:

git diff --name-only HEAD

Map changed files to E2E tests using these rules:

Changed File Pattern	Relevant E2E Tests
`src/pages/Sessions*.tsx`	`playwright/tests/session-*.spec.ts`
`src/pages/Accounts*.tsx`	`playwright/tests/account-*.spec.ts`
`src/pages/Contacts*.tsx`	`playwright/tests/contact-*.spec.ts`
`src/components/tables/*Table.tsx`	E2E for that domain
`src/hooks/use*.ts`	E2E for features using that hook
`src/services/*.service.ts`	E2E for features using that service

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

Result	Action
All pass	Continue to Phase 4
Failures	Evaluate if failure is due to our changes

If E2E fails due to our changes:

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

If E2E fails due to pre-existing issues:

Inform user of unrelated failure
Ask whether to skip or fix

Phase 4: Evaluate Coverage Needs

Assess if new tests are needed for the changed files.

Identify changed testable files (.ts, .tsx in src/, excluding tests)
For each file, check:
- Does a corresponding test file exist?
- Does the test cover the changed functionality?
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:

Code Type	Test Type	Location
Component	Unit	`src/**/__tests__/[name].test.tsx`
Hook	Unit	`src/hooks/__tests__/[name].test.ts`
Service	Unit	`src/services/__tests__/[name].test.ts`
Page flow	E2E	`playwright/tests/[feature].spec.ts`

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

Result	Action
Pass	Continue to Phase 8
Errors	Run `--fix`, then fix remaining manually

# 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/.

Get changed source files:

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

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/

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?
Categorize updates needed:

Update Type	Action
File path renamed	Auto-update (context-aware, not blind replacement)
Function/type renamed (clear 1:1)	Auto-update with verification
Code deleted	Flag for user - may need doc section removal
Pattern/behavior changed	Flag for user - requires rewrite
Line number references	Flag for user - inherently unstable

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,
    },
  ];
}

Result	Action
Update docs	Apply updates, continue to Phase 7
Review each	Show diff for each doc, apply approved changes
Skip	Continue to Phase 8 without doc changes
No stale refs found	Continue to Phase 8 (no prompt needed)

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

Stage changed files:

git add <files>

Commit with descriptive message:

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

<body>

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

<approval_gates>

Approval Gates

Gate	Phase	Question
Pre-existing failures	1, 3	"Tests failed but unrelated to changes. Skip or fix?"
Coverage gaps	4	"Create tests for uncovered files?"
Doc sync	7	"Found stale doc references. Update?"
Commit scope	8	"Which files to commit?" (if mixed changes)

</approval_gates>

<quick_reference>

Quick Reference

# Phase 1: Unit tests
npm run test:unit -- --run

# Phase 3: Specific E2E
npx playwright test <spec-file> --retries=3

# Phase 6: Lint changed files
git diff --name-only HEAD | grep -E '\.(ts|tsx)$' | xargs npx eslint --max-warnings 0

For commands: references/commands.md For test locations: references/test-locations.md </quick_reference>

Guidelines

Run unit tests before E2E (faster feedback loop)
Only run E2E tests relevant to changes (not full suite)
Fix test failures before adding new tests
Lint after all test work is complete
Ask user before creating new test files
Sync documentation before committing to keep docs accurate
Doc updates are context-aware reads, not blind find/replace

References

references/commands.md - Full CI command reference
references/test-locations.md - Test file patterns and locations

<version_history>

Version History

v5.1.0 (2026-01-20): Add Phase 7 for documentation synchronization
- Detects when code changes affect .claude/rules/ and claude-patterns/
- Context-aware updates (reads doc, understands purpose)
- Auto-updates file paths and clear 1:1 renames
- Flags deletions, behavior changes, and line numbers for user review
- Known limitation: May miss some reference patterns
v5.0.0 (2026-01-20): Complete workflow restructure
- Phase 1: Run ALL unit tests first (not just audit)
- Phase 2-3: Evaluate and fix relevant E2E tests only
- Phase 4-5: Coverage evaluation moved after test validation
- Phase 6: Lint after all test work
- Commit only after everything passes
- Rationale: Catch test failures early, fix before committing
v4.1.0 (2025-01-18): AI optimization updates
- Add blockquote summary after title
- Soften directive language
v4.0.0 (2025-12-29): Slimmed down - removed checks handled by pre-push
- Removed: typecheck, unit tests, E2E tests (pre-push hook handles these)
- Kept: test coverage audit, selective lint, commit
v3.0.0 (2025-12-28): Refactored to follow skill-authoring-patterns
v1.0.0 (2025-11-30): Initial release </version_history>

test-and-commit

Test and Commit

When to Use

Workflow Overview