pan-wizard 2.8.1

package/pan-wizard-core/templates/codebase/concerns.md

@@ -0,0 +1,325 @@
+# Codebase Concerns Template
+
+Template for `.planning/codebase/CONCERNS.md` - captures known issues and areas requiring care.
+
+**Purpose:** Surface actionable warnings about the codebase. Focused on "what to watch out for when making changes."
+
+---
+
+## File Template
+
+```markdown
+# Codebase Concerns
+
+**Analysis Date:** [YYYY-MM-DD]
+
+## Risk Overview
+
+### Impact vs Probability
+
+```mermaid
+quadrantChart
+    title Risk Assessment
+    x-axis Low Probability --> High Probability
+    y-axis Low Impact --> High Impact
+    quadrant-1 Monitor
+    quadrant-2 Act Now
+    quadrant-3 Accept
+    quadrant-4 Mitigate
+```
+
+## Tech Debt
+
+**[Area/Component]:**
+- Issue: [What's the shortcut/workaround]
+- Why: [Why it was done this way]
+- Impact: [What breaks or degrades because of it]
+- Fix approach: [How to properly address it]
+
+**[Area/Component]:**
+- Issue: [What's the shortcut/workaround]
+- Why: [Why it was done this way]
+- Impact: [What breaks or degrades because of it]
+- Fix approach: [How to properly address it]
+
+## Known Bugs
+
+**[Bug description]:**
+- Symptoms: [What happens]
+- Trigger: [How to reproduce]
+- Workaround: [Temporary mitigation if any]
+- Root cause: [If known]
+- Blocked by: [If waiting on something]
+
+**[Bug description]:**
+- Symptoms: [What happens]
+- Trigger: [How to reproduce]
+- Workaround: [Temporary mitigation if any]
+- Root cause: [If known]
+
+## Security Considerations
+
+**[Area requiring security care]:**
+- Risk: [What could go wrong]
+- Current mitigation: [What's in place now]
+- Recommendations: [What should be added]
+
+**[Area requiring security care]:**
+- Risk: [What could go wrong]
+- Current mitigation: [What's in place now]
+- Recommendations: [What should be added]
+
+## Performance Bottlenecks
+
+**[Slow operation/endpoint]:**
+- Problem: [What's slow]
+- Measurement: [Actual numbers: "500ms p95", "2s load time"]
+- Cause: [Why it's slow]
+- Improvement path: [How to speed it up]
+
+**[Slow operation/endpoint]:**
+- Problem: [What's slow]
+- Measurement: [Actual numbers]
+- Cause: [Why it's slow]
+- Improvement path: [How to speed it up]
+
+## Fragile Areas
+
+**[Component/Module]:**
+- Why fragile: [What makes it break easily]
+- Common failures: [What typically goes wrong]
+- Safe modification: [How to change it without breaking]
+- Test coverage: [Is it tested? Gaps?]
+
+**[Component/Module]:**
+- Why fragile: [What makes it break easily]
+- Common failures: [What typically goes wrong]
+- Safe modification: [How to change it without breaking]
+- Test coverage: [Is it tested? Gaps?]
+
+## Scaling Limits
+
+**[Resource/System]:**
+- Current capacity: [Numbers: "100 req/sec", "10k users"]
+- Limit: [Where it breaks]
+- Symptoms at limit: [What happens]
+- Scaling path: [How to increase capacity]
+
+## Dependencies at Risk
+
+**[Package/Service]:**
+- Risk: [e.g., "deprecated", "unmaintained", "breaking changes coming"]
+- Impact: [What breaks if it fails]
+- Migration plan: [Alternative or upgrade path]
+
+## Missing Critical Features
+
+**[Feature gap]:**
+- Problem: [What's missing]
+- Current workaround: [How users cope]
+- Blocks: [What can't be done without it]
+- Implementation complexity: [Rough effort estimate]
+
+## Test Coverage Gaps
+
+**[Untested area]:**
+- What's not tested: [Specific functionality]
+- Risk: [What could break unnoticed]
+- Priority: [High/Medium/Low]
+- Difficulty to test: [Why it's not tested yet]
+
+---
+
+*Concerns audit: [date]*
+*Update as issues are fixed or new ones discovered*
+```
+
+<good_examples>
+```markdown
+# Codebase Concerns
+
+**Analysis Date:** 2025-01-20
+
+## Tech Debt
+
+**Database queries in React components:**
+- Issue: Direct Supabase queries in 15+ page components instead of server actions
+- Files: `app/dashboard/page.tsx`, `app/profile/page.tsx`, `app/courses/[id]/page.tsx`, `app/settings/page.tsx` (and 11 more in `app/`)
+- Why: Rapid prototyping during MVP phase
+- Impact: Can't implement RLS properly, exposes DB structure to client
+- Fix approach: Move all queries to server actions in `app/actions/`, add proper RLS policies
+
+**Manual webhook signature validation:**
+- Issue: Copy-pasted Stripe webhook verification code in 3 different endpoints
+- Files: `app/api/webhooks/stripe/route.ts`, `app/api/webhooks/checkout/route.ts`, `app/api/webhooks/subscription/route.ts`
+- Why: Each webhook added ad-hoc without abstraction
+- Impact: Easy to miss verification in new webhooks (security risk)
+- Fix approach: Create shared `lib/stripe/validate-webhook.ts` middleware
+
+## Known Bugs
+
+**Race condition in subscription updates:**
+- Symptoms: User shows as "free" tier for 5-10 seconds after successful payment
+- Trigger: Fast navigation after Stripe checkout redirect, before webhook processes
+- Files: `app/checkout/success/page.tsx` (redirect handler), `app/api/webhooks/stripe/route.ts` (webhook)
+- Workaround: Stripe webhook eventually updates status (self-heals)
+- Root cause: Webhook processing slower than user navigation, no optimistic UI update
+- Fix: Add polling in `app/checkout/success/page.tsx` after redirect
+
+**Inconsistent session state after logout:**
+- Symptoms: User redirected to /dashboard after logout instead of /login
+- Trigger: Logout via button in mobile nav (desktop works fine)
+- File: `components/MobileNav.tsx` (line ~45, logout handler)
+- Workaround: Manual URL navigation to /login works
+- Root cause: Mobile nav component not awaiting supabase.auth.signOut()
+- Fix: Add await to logout handler in `components/MobileNav.tsx`
+
+## Security Considerations
+
+**Admin role check client-side only:**
+- Risk: Admin dashboard pages check isAdmin from Supabase client, no server verification
+- Files: `app/admin/page.tsx`, `app/admin/users/page.tsx`, `components/AdminGuard.tsx`
+- Current mitigation: None (relying on UI hiding)
+- Recommendations: Add middleware to admin routes in `middleware.ts`, verify role server-side
+
+**Unvalidated file uploads:**
+- Risk: Users can upload any file type to avatar bucket (no size/type validation)
+- File: `components/AvatarUpload.tsx` (upload handler)
+- Current mitigation: Supabase bucket limits to 2MB (configured in dashboard)
+- Recommendations: Add file type validation (image/* only) in `lib/storage/validate.ts`
+
+## Performance Bottlenecks
+
+**/api/courses endpoint:**
+- Problem: Fetching all courses with nested lessons and authors
+- File: `app/api/courses/route.ts`
+- Measurement: 1.2s p95 response time with 50+ courses
+- Cause: N+1 query pattern (separate query per course for lessons)
+- Improvement path: Use Prisma include to eager-load lessons in `lib/db/courses.ts`, add Redis caching
+
+**Dashboard initial load:**
+- Problem: Waterfall of 5 serial API calls on mount
+- File: `app/dashboard/page.tsx`
+- Measurement: 3.5s until interactive on slow 3G
+- Cause: Each component fetches own data independently
+- Improvement path: Convert to Server Component with single parallel fetch
+
+## Fragile Areas
+
+**Authentication middleware chain:**
+- File: `middleware.ts`
+- Why fragile: 4 different middleware functions run in specific order (auth -> role -> subscription -> logging)
+- Common failures: Middleware order change breaks everything, hard to debug
+- Safe modification: Add tests before changing order, document dependencies in comments
+- Test coverage: No integration tests for middleware chain (only unit tests)
+
+**Stripe webhook event handling:**
+- File: `app/api/webhooks/stripe/route.ts`
+- Why fragile: Giant switch statement with 12 event types, shared transaction logic
+- Common failures: New event type added without handling, partial DB updates on error
+- Safe modification: Extract each event handler to `lib/stripe/handlers/*.ts`
+- Test coverage: Only 3 of 12 event types have tests
+
+## Scaling Limits
+
+**Supabase Free Tier:**
+- Current capacity: 500MB database, 1GB file storage, 2GB bandwidth/month
+- Limit: ~5000 users estimated before hitting limits
+- Symptoms at limit: 429 rate limit errors, DB writes fail
+- Scaling path: Upgrade to Pro ($25/mo) extends to 8GB DB, 100GB storage
+
+**Server-side render blocking:**
+- Current capacity: ~50 concurrent users before slowdown
+- Limit: Vercel Hobby plan (10s function timeout, 100GB-hrs/mo)
+- Symptoms at limit: 504 gateway timeouts on course pages
+- Scaling path: Upgrade to Vercel Pro ($20/mo), add edge caching
+
+## Dependencies at Risk
+
+**react-hot-toast:**
+- Risk: Unmaintained (last update 18 months ago), React 19 compatibility unknown
+- Impact: Toast notifications break, no graceful degradation
+- Migration plan: Switch to sonner (actively maintained, similar API)
+
+## Missing Critical Features
+
+**Payment failure handling:**
+- Problem: No retry mechanism or user notification when subscription payment fails
+- Current workaround: Users manually re-enter payment info (if they notice)
+- Blocks: Can't retain users with expired cards, no dunning process
+- Implementation complexity: Medium (Stripe webhooks + email flow + UI)
+
+**Course progress tracking:**
+- Problem: No persistent state for which lessons completed
+- Current workaround: Users manually track progress
+- Blocks: Can't show completion percentage, can't recommend next lesson
+- Implementation complexity: Low (add completed_lessons junction table)
+
+## Test Coverage Gaps
+
+**Payment flow end-to-end:**
+- What's not tested: Full Stripe checkout -> webhook -> subscription activation flow
+- Risk: Payment processing could break silently (has happened twice)
+- Priority: High
+- Difficulty to test: Need Stripe test fixtures and webhook simulation setup
+
+**Error boundary behavior:**
+- What's not tested: How app behaves when components throw errors
+- Risk: White screen of death for users, no error reporting
+- Priority: Medium
+- Difficulty to test: Need to intentionally trigger errors in test environment
+
+---
+
+*Concerns audit: 2025-01-20*
+*Update as issues are fixed or new ones discovered*
+```
+</good_examples>
+
+<guidelines>
+**What belongs in CONCERNS.md:**
+- Tech debt with clear impact and fix approach
+- Known bugs with reproduction steps
+- Security gaps and mitigation recommendations
+- Performance bottlenecks with measurements
+- Fragile code that breaks easily
+- Scaling limits with numbers
+- Dependencies that need attention
+- Missing features that block workflows
+- Test coverage gaps
+
+**What does NOT belong here:**
+- Opinions without evidence ("code is messy")
+- Complaints without solutions ("auth sucks")
+- Future feature ideas (that's for product planning)
+- Normal TODOs (those live in code comments)
+- Architectural decisions that are working fine
+- Minor code style issues
+
+**When filling this template:**
+- **Always include file paths** - Concerns without locations are not actionable. Use backticks: `src/file.ts`
+- Be specific with measurements ("500ms p95" not "slow")
+- Include reproduction steps for bugs
+- Suggest fix approaches, not just problems
+- Focus on actionable items
+- Prioritize by risk/impact
+- Update as issues get resolved
+- Add new concerns as discovered
+
+**Tone guidelines:**
+- Professional, not emotional ("N+1 query pattern" not "terrible queries")
+- Solution-oriented ("Fix: add index" not "needs fixing")
+- Risk-focused ("Could expose user data" not "security is bad")
+- Factual ("3.5s load time" not "really slow")
+
+**Useful for phase planning when:**
+- Deciding what to work on next
+- Estimating risk of changes
+- Understanding where to be careful
+- Prioritizing improvements
+- Onboarding new Claude contexts
+- Planning refactoring work
+
+**How this gets populated:**
+Explore agents detect these during codebase mapping. Manual additions welcome for human-discovered issues. This is living documentation, not a complaint list.
+</guidelines>

package/pan-wizard-core/templates/codebase/conventions.md

@@ -0,0 +1,307 @@
+# Coding Conventions Template
+
+Template for `.planning/codebase/CONVENTIONS.md` - captures coding style and patterns.
+
+**Purpose:** Document how code is written in this codebase. Prescriptive guide for Claude to match existing style.
+
+---
+
+## File Template
+
+```markdown
+# Coding Conventions
+
+**Analysis Date:** [YYYY-MM-DD]
+
+## Naming Patterns
+
+**Files:**
+- [Pattern: e.g., "kebab-case for all files"]
+- [Test files: e.g., "*.test.ts alongside source"]
+- [Components: e.g., "PascalCase.tsx for React components"]
+
+**Functions:**
+- [Pattern: e.g., "camelCase for all functions"]
+- [Async: e.g., "no special prefix for async functions"]
+- [Handlers: e.g., "handleEventName for event handlers"]
+
+**Variables:**
+- [Pattern: e.g., "camelCase for variables"]
+- [Constants: e.g., "UPPER_SNAKE_CASE for constants"]
+- [Private: e.g., "_prefix for private members" or "no prefix"]
+
+**Types:**
+- [Interfaces: e.g., "PascalCase, no I prefix"]
+- [Types: e.g., "PascalCase for type aliases"]
+- [Enums: e.g., "PascalCase for enum name, UPPER_CASE for values"]
+
+## Code Style
+
+**Formatting:**
+- [Tool: e.g., "Prettier with config in .prettierrc"]
+- [Line length: e.g., "100 characters max"]
+- [Quotes: e.g., "single quotes for strings"]
+- [Semicolons: e.g., "required" or "omitted"]
+
+**Linting:**
+- [Tool: e.g., "ESLint with eslint.config.js"]
+- [Rules: e.g., "extends airbnb-base, no console in production"]
+- [Run: e.g., "npm run lint"]
+
+## Import Organization
+
+**Order:**
+1. [e.g., "External packages (react, express, etc.)"]
+2. [e.g., "Internal modules (@/lib, @/components)"]
+3. [e.g., "Relative imports (., ..)"]
+4. [e.g., "Type imports (import type {})"]
+
+**Grouping:**
+- [Blank lines: e.g., "blank line between groups"]
+- [Sorting: e.g., "alphabetical within each group"]
+
+**Path Aliases:**
+- [Aliases used: e.g., "@/ for src/, @components/ for src/components/"]
+
+## Error Handling
+
+**Patterns:**
+- [Strategy: e.g., "throw errors, catch at boundaries"]
+- [Custom errors: e.g., "extend Error class, named *Error"]
+- [Async: e.g., "use try/catch, no .catch() chains"]
+
+**Error Types:**
+- [When to throw: e.g., "invalid input, missing dependencies"]
+- [When to return: e.g., "expected failures return Result<T, E>"]
+- [Logging: e.g., "log error with context before throwing"]
+
+## Logging
+
+**Framework:**
+- [Tool: e.g., "console.log, pino, winston"]
+- [Levels: e.g., "debug, info, warn, error"]
+
+**Patterns:**
+- [Format: e.g., "structured logging with context object"]
+- [When: e.g., "log state transitions, external calls"]
+- [Where: e.g., "log at service boundaries, not in utils"]
+
+## Comments
+
+**When to Comment:**
+- [e.g., "explain why, not what"]
+- [e.g., "document business logic, algorithms, edge cases"]
+- [e.g., "avoid obvious comments like // increment counter"]
+
+**JSDoc/TSDoc:**
+- [Usage: e.g., "required for public APIs, optional for internal"]
+- [Format: e.g., "use @param, @returns, @throws tags"]
+
+**TODO Comments:**
+- [Pattern: e.g., "// TODO(username): description"]
+- [Tracking: e.g., "link to issue number if available"]
+
+## Function Design
+
+**Size:**
+- [e.g., "keep under 50 lines, extract helpers"]
+
+**Parameters:**
+- [e.g., "max 3 parameters, use object for more"]
+- [e.g., "destructure objects in parameter list"]
+
+**Return Values:**
+- [e.g., "explicit returns, no implicit undefined"]
+- [e.g., "return early for guard clauses"]
+
+## Module Design
+
+**Exports:**
+- [e.g., "named exports preferred, default exports for React components"]
+- [e.g., "export from index.ts for public API"]
+
+**Barrel Files:**
+- [e.g., "use index.ts to re-export public API"]
+- [e.g., "avoid circular dependencies"]
+
+---
+
+*Convention analysis: [date]*
+*Update when patterns change*
+```
+
+<good_examples>
+```markdown
+# Coding Conventions
+
+**Analysis Date:** 2025-01-20
+
+## Naming Patterns
+
+**Files:**
+- kebab-case for all files (command-handler.ts, user-service.ts)
+- *.test.ts alongside source files
+- index.ts for barrel exports
+
+**Functions:**
+- camelCase for all functions
+- No special prefix for async functions
+- handleEventName for event handlers (handleClick, handleSubmit)
+
+**Variables:**
+- camelCase for variables
+- UPPER_SNAKE_CASE for constants (MAX_RETRIES, API_BASE_URL)
+- No underscore prefix (no private marker in TS)
+
+**Types:**
+- PascalCase for interfaces, no I prefix (User, not IUser)
+- PascalCase for type aliases (UserConfig, ResponseData)
+- PascalCase for enum names, UPPER_CASE for values (Status.PENDING)
+
+## Code Style
+
+**Formatting:**
+- Prettier with .prettierrc
+- 100 character line length
+- Single quotes for strings
+- Semicolons required
+- 2 space indentation
+
+**Linting:**
+- ESLint with eslint.config.js
+- Extends @typescript-eslint/recommended
+- No console.log in production code (use logger)
+- Run: npm run lint
+
+## Import Organization
+
+**Order:**
+1. External packages (react, express, commander)
+2. Internal modules (@/lib, @/services)
+3. Relative imports (./utils, ../types)
+4. Type imports (import type { User })
+
+**Grouping:**
+- Blank line between groups
+- Alphabetical within each group
+- Type imports last within each group
+
+**Path Aliases:**
+- @/ maps to src/
+- No other aliases defined
+
+## Error Handling
+
+**Patterns:**
+- Throw errors, catch at boundaries (route handlers, main functions)
+- Extend Error class for custom errors (ValidationError, NotFoundError)
+- Async functions use try/catch, no .catch() chains
+
+**Error Types:**
+- Throw on invalid input, missing dependencies, invariant violations
+- Log error with context before throwing: logger.error({ err, userId }, 'Failed to process')
+- Include cause in error message: new Error('Failed to X', { cause: originalError })
+
+## Logging
+
+**Framework:**
+- pino logger instance exported from lib/logger.ts
+- Levels: debug, info, warn, error (no trace)
+
+**Patterns:**
+- Structured logging with context: logger.info({ userId, action }, 'User action')
+- Log at service boundaries, not in utility functions
+- Log state transitions, external API calls, errors
+- No console.log in committed code
+
+## Comments
+
+**When to Comment:**
+- Explain why, not what: // Retry 3 times because API has transient failures
+- Document business rules: // Users must verify email within 24 hours
+- Explain non-obvious algorithms or workarounds
+- Avoid obvious comments: // set count to 0
+
+**JSDoc/TSDoc:**
+- Required for public API functions
+- Optional for internal functions if signature is self-explanatory
+- Use @param, @returns, @throws tags
+
+**TODO Comments:**
+- Format: // TODO: description (no username, using git blame)
+- Link to issue if exists: // TODO: Fix race condition (issue #123)
+
+## Function Design
+
+**Size:**
+- Keep under 50 lines
+- Extract helpers for complex logic
+- One level of abstraction per function
+
+**Parameters:**
+- Max 3 parameters
+- Use options object for 4+ parameters: function create(options: CreateOptions)
+- Destructure in parameter list: function process({ id, name }: ProcessParams)
+
+**Return Values:**
+- Explicit return statements
+- Return early for guard clauses
+- Use Result<T, E> type for expected failures
+
+## Module Design
+
+**Exports:**
+- Named exports preferred
+- Default exports only for React components
+- Export public API from index.ts barrel files
+
+**Barrel Files:**
+- index.ts re-exports public API
+- Keep internal helpers private (don't export from index)
+- Avoid circular dependencies (import from specific files if needed)
+
+---
+
+*Convention analysis: 2025-01-20*
+*Update when patterns change*
+```
+</good_examples>
+
+<guidelines>
+**What belongs in CONVENTIONS.md:**
+- Naming patterns observed in the codebase
+- Formatting rules (Prettier config, linting rules)
+- Import organization patterns
+- Error handling strategy
+- Logging approach
+- Comment conventions
+- Function and module design patterns
+
+**What does NOT belong here:**
+- Architecture decisions (that's ARCHITECTURE.md)
+- Technology choices (that's STACK.md)
+- Test patterns (that's TESTING.md)
+- File organization (that's STRUCTURE.md)
+
+**When filling this template:**
+- Check .prettierrc, .eslintrc, or similar config files
+- Examine 5-10 representative source files for patterns
+- Look for consistency: if 80%+ follows a pattern, document it
+- Be prescriptive: "Use X" not "Sometimes Y is used"
+- Note deviations: "Legacy code uses Y, new code should use X"
+- Keep under ~150 lines total
+
+**Useful for phase planning when:**
+- Writing new code (match existing style)
+- Adding features (follow naming patterns)
+- Refactoring (apply consistent conventions)
+- Code review (check against documented patterns)
+- Onboarding (understand style expectations)
+
+**Analysis approach:**
+- Scan src/ directory for file naming patterns
+- Check package.json scripts for lint/format commands
+- Read 5-10 files to identify function naming, error handling
+- Look for config files (.prettierrc, eslint.config.js)
+- Note patterns in imports, comments, function signatures
+</guidelines>