feat: add file paths to codebase mapping output

- Agent prompts now explicitly require file paths in findings
- Templates updated with backtick-formatted path examples
- CONCERNS.md examples show Files: field for every issue
- ARCHITECTURE.md now welcomes file paths as concrete examples
- Makes codebase docs actionable for Claude during planning

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

get-shit-done/templates/codebase/architecture.md

@@ -124,18 +124,21 @@ Template for `.planning/codebase/ARCHITECTURE.md` - captures conceptual code org
 **Command Layer:**
 - Purpose: Parse user input and route to appropriate handler
 - Contains: Command definitions, argument parsing, help text
+- Location: `src/commands/*.ts`
 - Depends on: Service layer for business logic
-- Used by: CLI entry point (src/index.ts)
+- Used by: CLI entry point (`src/index.ts`)
 
 **Service Layer:**
 - Purpose: Core business logic
 - Contains: FileService, TemplateService, InstallService
+- Location: `src/services/*.ts`
 - Depends on: File system utilities, external tools
 - Used by: Command handlers
 
 **Utility Layer:**
 - Purpose: Shared helpers and abstractions
 - Contains: File I/O wrappers, path resolution, string formatting
+- Location: `src/utils/*.ts`
 - Depends on: Node.js built-ins only
 - Used by: Service layer
 
@@ -145,8 +148,8 @@ Template for `.planning/codebase/ARCHITECTURE.md` - captures conceptual code org
 
 1. User runs: `gsd new-project`
 2. Commander parses args and flags
-3. Command handler invoked (commands/new-project.ts)
-4. Handler calls service methods (e.g., ProjectService.create())
+3. Command handler invoked (`src/commands/new-project.ts`)
+4. Handler calls service methods (`src/services/project.ts` → `create()`)
 5. Service reads templates, processes files, writes output
 6. Results logged to console
 7. Process exits with status code
@@ -160,12 +163,12 @@ Template for `.planning/codebase/ARCHITECTURE.md` - captures conceptual code org
 
 **Service:**
 - Purpose: Encapsulate business logic for a domain
-- Examples: FileService, TemplateService, ProjectService
+- Examples: `src/services/file.ts`, `src/services/template.ts`, `src/services/project.ts`
 - Pattern: Singleton-like (imported as modules, not instantiated)
 
 **Command:**
 - Purpose: CLI command definition
-- Examples: new-project, plan-phase, execute-plan
+- Examples: `src/commands/new-project.ts`, `src/commands/plan-phase.ts`
 - Pattern: Commander.js command registration
 
 **Template:**
@@ -176,12 +179,12 @@ Template for `.planning/codebase/ARCHITECTURE.md` - captures conceptual code org
 ## Entry Points
 
 **CLI Entry:**
-- Location: src/index.ts
+- Location: `src/index.ts`
 - Triggers: User runs `gsd <command>`
 - Responsibilities: Register commands, parse args, display help
 
 **Commands:**
-- Location: src/commands/*.ts
+- Location: `src/commands/*.ts`
 - Triggers: Matched command from CLI
 - Responsibilities: Validate input, call services, format output
 
@@ -229,11 +232,14 @@ Template for `.planning/codebase/ARCHITECTURE.md` - captures conceptual code org
 - Cross-cutting concerns (logging, auth, validation)
 
 **What does NOT belong here:**
-- Specific file paths (that's STRUCTURE.md)
+- Exhaustive file listings (that's STRUCTURE.md)
 - Technology choices (that's STACK.md)
 - Line-by-line code walkthrough (defer to code reading)
 - Implementation details of specific features
 
+**File paths ARE welcome:**
+Include file paths as concrete examples of abstractions. Use backtick formatting: `src/services/user.ts`. This makes the architecture document actionable for Claude when planning.
+
 **When filling this template:**
 - Read main entry points (index, server, main)
 - Identify layers by reading imports/dependencies

get-shit-done/templates/codebase/concerns.md

@@ -129,70 +129,80 @@ Template for `.planning/codebase/CONCERNS.md` - captures known issues and areas
 
 **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
+- 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 validateStripeWebhook middleware
+- 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: Poll subscription status after checkout redirect, don't rely solely on webhook
+- 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 MobileNav.tsx
+- 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, verify role server-side in Server Components
+- 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), virus scanning for larger scale
+- 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, add Redis caching
+- 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: Server Component with single parallel fetch, or React Server Components
+- 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 separate function, add comprehensive error handling
+- Safe modification: Extract each event handler to `lib/stripe/handlers/*.ts`
 - Test coverage: Only 3 of 12 event types have tests
 
 ## Scaling Limits
@@ -272,6 +282,7 @@ Template for `.planning/codebase/CONCERNS.md` - captures known issues and areas
 - 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

get-shit-done/templates/codebase/stack.md

@@ -103,7 +103,7 @@ Template for `.planning/codebase/STACK.md` - captures the technology foundation.
 
 **Package Manager:**
 - npm 10.x
-- Lockfile: package-lock.json present
+- Lockfile: `package-lock.json` present
 
 ## Frameworks
 
@@ -135,8 +135,8 @@ Template for `.planning/codebase/STACK.md` - captures the technology foundation.
 - Configuration via CLI flags only
 
 **Build:**
-- tsconfig.json - TypeScript compiler options
-- vitest.config.ts - Test runner configuration
+- `tsconfig.json` - TypeScript compiler options
+- `vitest.config.ts` - Test runner configuration
 
 ## Platform Requirements
 

get-shit-done/templates/codebase/structure.md

@@ -172,21 +172,21 @@ get-shit-done/
 ## Key File Locations
 
 **Entry Points:**
-- bin/install.js: Installation script (npx entry)
+- `bin/install.js` - Installation script (npx entry)
 
 **Configuration:**
-- package.json: Project metadata, dependencies, bin entry
-- .gitignore: Excluded files
+- `package.json` - Project metadata, dependencies, bin entry
+- `.gitignore` - Excluded files
 
 **Core Logic:**
-- bin/install.js: All installation logic (file copying, path replacement)
+- `bin/install.js` - All installation logic (file copying, path replacement)
 
 **Testing:**
-- tests/: Test files (if present)
+- `tests/` - Test files (if present)
 
 **Documentation:**
-- README.md: User-facing installation and usage guide
-- CLAUDE.md: Instructions for Claude Code when working in this repo
+- `README.md` - User-facing installation and usage guide
+- `CLAUDE.md` - Instructions for Claude Code when working in this repo
 
 ## Naming Conventions
 
@@ -206,25 +206,25 @@ get-shit-done/
 ## Where to Add New Code
 
 **New Slash Command:**
-- Primary code: commands/gsd/{command-name}.md
-- Tests: tests/commands/{command-name}.test.js (if testing implemented)
-- Documentation: Update README.md with new command
+- Primary code: `commands/gsd/{command-name}.md`
+- Tests: `tests/commands/{command-name}.test.js` (if testing implemented)
+- Documentation: Update `README.md` with new command
 
 **New Template:**
-- Implementation: get-shit-done/templates/{name}.md
+- Implementation: `get-shit-done/templates/{name}.md`
 - Documentation: Template is self-documenting (includes guidelines)
 
 **New Workflow:**
-- Implementation: get-shit-done/workflows/{name}.md
-- Usage: Reference from command with @~/.claude/get-shit-done/workflows/{name}.md
+- Implementation: `get-shit-done/workflows/{name}.md`
+- Usage: Reference from command with `@~/.claude/get-shit-done/workflows/{name}.md`
 
 **New Reference Document:**
-- Implementation: get-shit-done/references/{name}.md
+- Implementation: `get-shit-done/references/{name}.md`
 - Usage: Reference from commands/workflows as needed
 
 **Utilities:**
-- No utilities yet (install.js is monolithic)
-- If extracted: src/utils/
+- No utilities yet (`install.js` is monolithic)
+- If extracted: `src/utils/`
 
 ## Special Directories
 

get-shit-done/workflows/map-codebase.md

@@ -13,6 +13,9 @@ Each agent has fresh context and focuses on specific aspects. Output is concise
 
 **Document quality over length:**
 Include enough detail to be useful as reference. Prioritize practical examples (especially code patterns) over arbitrary brevity. A 200-line TESTING.md with real patterns is more valuable than a 74-line summary.
+
+**Always include file paths:**
+Documents are reference material for Claude when planning/executing. Vague descriptions like "UserService handles users" are not actionable. Always include actual file paths formatted with backticks: `src/services/user.ts`. This allows Claude to navigate directly to relevant code without re-searching. Do NOT include line numbers (they go stale), just file paths.
 </philosophy>
 
 <process>
@@ -83,6 +86,8 @@ Prompt:
 ```
 Analyze this codebase for technology stack and external integrations.
 
+IMPORTANT: Always include actual file paths in your findings. Use backtick formatting like `src/config/database.ts`. This makes the output actionable for planning.
+
 Focus areas:
 1. Languages (check file extensions, package manifests)
 2. Runtime environment (Node.js, Python, etc. - check .nvmrc, .python-version, engines field)
@@ -104,6 +109,11 @@ Output findings for populating these sections:
 - STACK.md: Languages, Runtime, Frameworks, Dependencies, Configuration
 - INTEGRATIONS.md: External APIs, Services, Third-party tools
 
+For each finding, include the file path where you found it. Example:
+- "TypeScript 5.3 - `package.json`"
+- "Supabase client - `src/lib/supabase.ts`"
+- "Stripe integration - `src/services/stripe.ts`, `src/webhooks/stripe.ts`"
+
 If something is not found, note "Not detected" for that category.
 ```
 
@@ -120,6 +130,8 @@ Prompt:
 ```
 Analyze this codebase architecture and directory structure.
 
+IMPORTANT: Always include actual file paths in your findings. Use backtick formatting like `src/index.ts`. This makes the output actionable for planning.
+
 Focus areas:
 1. Overall architectural pattern (monolith, microservices, layered, etc.)
 2. Conceptual layers (API, service, data, utility)
@@ -140,6 +152,11 @@ Output findings for populating these sections:
 - ARCHITECTURE.md: Pattern, Layers, Data Flow, Abstractions, Entry Points
 - STRUCTURE.md: Directory layout, Organization, Key locations
 
+For each finding, include the file path. Examples:
+- "CLI entry point: `bin/install.js`"
+- "Service layer: `src/services/*.ts` (UserService, ProjectService)"
+- "API routes: `src/routes/api/*.ts`"
+
 If something is not clear, provide best-guess interpretation based on code structure.
 ```
 
@@ -156,6 +173,8 @@ Prompt:
 ```
 Analyze this codebase for coding conventions and testing practices.
 
+IMPORTANT: Always include actual file paths in your findings. Use backtick formatting like `vitest.config.ts`. This makes the output actionable for planning.
+
 Focus areas:
 1. Code style (indentation, quotes, semicolons, formatting)
 2. File naming conventions (kebab-case, PascalCase, etc.)
@@ -177,6 +196,11 @@ Output findings for populating these sections:
 - CONVENTIONS.md: Code Style, Naming, Patterns, Documentation
 - TESTING.md: Framework, Structure, Coverage, Tools
 
+For each finding, include file paths. Examples:
+- "Prettier config: `.prettierrc`"
+- "Test pattern: `src/**/*.test.ts` (co-located with source)"
+- "Example of naming convention: `src/services/user-service.ts`"
+
 Look at actual code files to infer conventions if config files are missing.
 ```
 
@@ -193,6 +217,8 @@ Prompt:
 ```
 Analyze this codebase for technical debt, known issues, and areas of concern.
 
+CRITICAL: Always include actual file paths in your findings. Use backtick formatting like `src/auth/login.ts`. Concerns without file paths are not actionable. For each issue found, specify exactly where it is.
+
 Focus areas:
 1. TODO and FIXME comments
 2. Complex or hard-to-understand code
@@ -215,6 +241,11 @@ Search for:
 Output findings for populating:
 - CONCERNS.md: Technical Debt, Issues, Security, Performance, Documentation
 
+For EVERY concern, include file paths. Examples:
+- "Direct DB queries in components: `src/pages/Dashboard.tsx`, `src/pages/Profile.tsx`"
+- "Missing error handling: `src/api/webhook.ts` (Stripe webhook has no try/catch)"
+- "TODO: 'fix race condition' in `src/services/subscription.ts`"
+
 Be constructive - focus on actionable concerns, not nitpicks.
 If codebase is clean, note that rather than inventing problems.
 ```