Plan Review Checklist

Plan Review Checklist

Detailed criteria for reviewing plans and phases against templates and codebase patterns.

Why Template Compliance Matters

The user created these templates to ensure planning documents are complete before implementation begins. Each required section exists because missing it caused problems:

Catching missing sections now costs 30 seconds. Discovering them during implementation costs hours.

Plan.md Required Sections

From ../create-plan/references/PLAN-TEMPLATE.md:

YAML Frontmatter

• title field present
• status field (pending/in-progress/done)
• priority field
• tags array
• created date
• updated date

Executive Summary

• "The Mission" one-sentence objective
• "The Big Shift" architectural change description
• Primary Deliverables list (3 items)

Phasing Strategy

• Strategy description
• Phase Constraints subsection (size, scope, dependencies, review gate)
• Phase File Naming subsection (pattern, examples)
• Phase Table with columns: Phase, Title, Focus, Status

Architectural North Star

• At least one pattern defined
• Each pattern has Core Principle and Enforcement

Project Framework Alignment

• Component Usage Priority (1. project component library, 2. shadcn, 3. custom)
• Required Utilities table (Server Action pattern, data loaders, etc.)
• Reference to project documentation or patterns

Security Requirements

• RLS Policy Rules subsection
• Input Validation subsection
• Authorization subsection
• Error Handling subsection

Implementation Standards

• Global Test Strategy
• Global Documentation Standard

Success Metrics & Quality Gates

• Project Success Metrics list
• Global Quality Gates checklist

Global Decision Log

• At least one ADR or placeholder
• ADR format: Status, Context, Decision, Consequences

Resources & References

• Links to relevant docs

Phase File Required Sections

From ../create-plan/references/PHASE-TEMPLATE.md:

YAML Frontmatter

• title field
• description one-sentence goal
• status field
• dependencies array
• tags array
• created and updated dates

Overview

• Brief description of deliverables
• Single-sentence Goal

Context & Workflow

• How This Phase Fits Into the Project (UI, Server, Database, Integrations)
• User Workflow (Trigger, Steps, Outcome)
• Problem Being Solved

Prerequisites & Clarifications

• Questions for User (with Context, Assumptions, Impact)
• Validation Checklist

Requirements

• Functional requirements list
• Technical constraints list

Decision Log

• Section present (even if empty initially)
• ADR format defined

Implementation Steps

• Step 0: TDD (first step) — tests written after code are often skipped; TDD ensures coverage
  • Backend Unit Tests (services, schemas, APIs) with real assertions
  • Frontend Component Tests using happy-dom and @testing-library/react
  • Run Tests (Should Fail - red phase of TDD)
• Numbered implementation steps
• Documentation Updates step

Verifiable Acceptance Criteria

• Critical Path checklist
• Quality Gates checklist
• Integration checklist

Quality Assurance

• Manual Testing section
• Automated Testing section
• Performance Testing section
• Review Checklist with /code-review reference

Dependencies

• Upstream (Required Before Starting)
• Downstream (Will Use This Phase)
• External Services

Completion Gate

• Sign-off checklist

Additional Checks

Phase Constraints

• Each phase file < 15KB
• Dependencies explicit in frontmatter
• Single implementation session scope

Cross-References

• Phase Table links to existing files
• Phase files reference correct plan.md
• Dependencies reference valid phase numbers

Project Pattern Checks

Verify these are correctly used (not just mentioned):

• Project component library used for UI (not raw HTML or custom equivalents)
• Server Actions use 'use server' + Zod validation + getSession() auth check
• RLS helpers used (your RLS helper function, your permission check function) -- not custom auth checks
• import 'server-only' present in all server-side files

Security Mentions

These checks prevent security issues from being designed into the feature:

• No USING(true) instruction present — would allow any user to access all rows
• account_id scoping mentioned — ensures multi-tenant data isolation
• Input validation mentioned — prevents malformed data and injection attacks
• Error handling patterns mentioned — prevents sensitive data leakage in error messages

Codebase Compliance Checks

These checks apply to phase files only (not plan.md). For each code block in the phase, verify patterns match the actual codebase.

Phase Type Classification

Classify the phase to determine which checks apply:

Check 1: Naming Conventions

How to verify: Glob for existing files matching the pattern, confirm the phase follows the same convention.

Check 2: Server Action Pattern

How to verify: Read an existing server-actions.ts file. Compare auth check, validation, and service usage.

// CORRECT pattern from codebase
'use server';

import { z } from 'zod';
import { createClient } from '@/lib/supabase/server';
import { getSession } from '@/lib/auth';
import { createFeatureService } from './feature.service';

const MySchema = z.object({ /* ... */ });

export async function myAction(formData: FormData) {
  const session = await getSession();        // ← Auth check FIRST
  if (!session) throw new Error('Unauthorized');

  const data = MySchema.parse(              // ← Zod validation
    Object.fromEntries(formData)
  );
  const supabase = await createClient();
  const service = createFeatureService(supabase);
  return service.doSomething(data);
}

Check 3: Account Resolution

How to verify: Read an existing server action that operates on account data.

// CORRECT: Resolve slug to ID via DB lookup
const { data: account } = await client
  .from('accounts')
  .select('id')
  .eq('slug', data.accountSlug)
  .single();

// CORRECT: Then check permission
const { data: hasPermission } = await client.rpc('has_permission', {
  user_id: user.id,
  account_id: account.id,
  permission_name: 'your_app.manage_feature',
});

Check 4: Import Patterns

How to verify: Read existing files to confirm import sources.

Check 5: TypeScript Compliance

How to verify: Check CLAUDE.md rules and existing code patterns.

Check 6: Service Factory Patterns

How to verify: Read an existing *.service.ts file or service function.

// CORRECT: Factory function wrapping a class
import 'server-only';

import { SupabaseClient } from '@supabase/supabase-js';
import type { Database } from '@/types/database';

export function createFeatureService(client: SupabaseClient<Database>) {
  return new FeatureService(client);
}

class FeatureService {
  private readonly namespace = 'feature';

  constructor(private readonly client: SupabaseClient<Database>) {}

  async getConfig(accountId: string) {
    const { data, error } = await this.client
      .from('feature_config')
      .select('*')
      .eq('account_id', accountId)
      .single();
    if (error) throw error;
    return data;
  }
}

Check 7: Export Patterns

How to verify: Check how existing features structure their exports.

Check 8: Error Handling

How to verify: Read existing server actions for error patterns.

Check 9: CLAUDE.md Rules

How to verify: Read CLAUDE.md and check phase steps against it.

Check 10: SQL Safety

How to verify: Read existing migrations for patterns.

Check 11: Test Infrastructure

How to verify: Read existing test files in __tests__/.

Check 12: Consistency

How to verify: Cross-reference the phase file internally and against plan.md.

Severity Definitions