@jamie-tam/forge 6.0.0

package/skills/discover-codebase-analysis/SKILL.md

@@ -0,0 +1,448 @@
+---
+name: discover-codebase-analysis
+description: "Use when the user opens an unfamiliar repo, says 'explain this codebase', 'what does this project do', 'map the architecture', 'find the entry points', 'what patterns does this use', or before any /feature or /harden on an existing codebase. Produces a structured codebase report (entry points, layers, conventions, hot files). Skip for greenfield work — no codebase to analyse."
+---
+
+# Discover Codebase Analysis
+
+Systematically analyze an existing codebase to understand its structure, patterns, conventions, and risks before planning any changes. This skill produces a structured report.
+
+**Announce at start:** "I'm using the discover-codebase-analysis skill to map the existing codebase before we plan changes."
+
+<HARD-GATE>
+On existing projects, this skill MUST run before plan-brainstorm. Do NOT propose architectural changes without understanding what already exists. Skipping codebase analysis leads to designs that fight the existing code instead of working with it.
+</HARD-GATE>
+
+---
+
+## I/O Contract
+
+| Field | Value |
+|---|---|
+| **Requires** | Existing codebase accessible in the working directory or specified path |
+| **Produces** | `.forge/work/{type}/{name}/codebase-analysis.md` |
+| **Feeds into** | `plan-brainstorm`, `plan-architecture`, `plan-task-decompose` |
+| **Updates manifest** | `artifacts.codebase-analysis` |
+
+---
+
+## Agent Dispatch
+
+Dispatch the **architect** subagent (Opus) to analyze the architecture. The architect agent specializes in system design evaluation, tradeoff analysis, and identifying architectural patterns and risks that a standard analysis might miss. The architect determines the appropriate depth based on the codebase size and complexity.
+
+**Note for legacy codebases:** Files exceeding 500 lines should be analyzed using `lsp_document_symbols` or read with `offset` + `limit` to avoid consuming excessive context.
+
+## Checklist
+
+Complete these steps in order:
+
+1. **Identify the scope of analysis** -- full project or targeted area
+2. **Graphify guard** -- run the status check from `protocols/graphify.md`. Offer install/build/update as appropriate. Graph data enriches steps 3-9.
+3. **Map project structure** -- directories, key files, entry points. If graph available: use communities as subsystem map, god nodes as critical components.
+4. **Identify technology stack** -- languages, frameworks, libraries, build tools
+5. **Analyze code patterns** -- architectural style, state management, error handling. If graph available: validate architecture claims against community boundaries.
+6. **Map conventions** -- naming, file organization, import style, component patterns
+7. **Trace dependency chains** -- for the area being modified. If graph available: use edge confidence labels (EXTRACTED = trusted, INFERRED = verify, AMBIGUOUS = investigate).
+8. **Assess test coverage** -- what is tested, what is not, testing approach
+9. **Flag risks** -- tight coupling, missing tests, tech debt, security concerns. If graph available: god nodes as coupling risks, AMBIGUOUS edges as investigation targets.
+10. **Write analysis report** -- structured document to `.forge/work/{type}/{name}/codebase-analysis.md`
+11. **Update feature manifest** -- record artifact path
+
+---
+
+## Process
+
+### Step 1: Identify Scope of Analysis
+
+Ask the user what they intend to change. This scopes the analysis:
+
+> "Before I analyze the codebase, what area are you planning to modify? This helps me focus the analysis on the most relevant parts."
+>
+> A) A specific feature area (tell me which one)
+> B) A specific set of files or directories
+> C) I need a full project overview first
+> D) I'm not sure yet -- help me understand the whole project
+
+For targeted analysis (A/B): deep-dive the specified area plus one level of dependencies.
+For full overview (C/D): breadth-first scan of the entire project, then depth on areas the user selects.
+
+### Step 1.5: Codex Mode Check
+
+Now that scope is known, run the Codex consent flow from `protocols/codex.md`. The selected mode applies for the rest of this skill's invocation — do not re-prompt at later Codex steps.
+
+- **Takeover:** Dispatch Codex with the scope from Step 1 + skill methodology + working directory. Skip Steps 2-10 (Codex runs them). Claude reviews Codex's output at Step 10.
+- **Verify** or **Skip / Codex unavailable:** Proceed with Steps 2-11 below. Step 9.5 will dispatch Codex to review Claude's analysis (Verify only).
+
+### Step 2: Graphify Guard
+
+Run the full graphify status check from `protocols/graphify.md` — see that protocol for the complete status table. Summary:
+
+1. Check three things:
+   - `graphify-out/graph.json` exists?
+   - `graphify --version` succeeds (CLI installed)?
+   - `~/.claude/skills/graphify/SKILL.md` exists (skill installed — required for `/graphify` to fire)?
+2. Offer the appropriate action based on status (install / install skill / build / update / use as-is). See the full table in `protocols/graphify.md`.
+3. If user accepts build/update → invoke the `/graphify` skill, then continue.
+4. If user declines update BUT `graph.json` already exists → continue using the existing graph as-is. Do NOT skip graph enrichment.
+5. If user declines install/build AND no graph exists → proceed without graph enrichment.
+
+**If graph is available after this step** (freshly built, updated, or existing), extract: god nodes, top 20 communities by cohesion, edge confidence labels (EXTRACTED/INFERRED/AMBIGUOUS).
+
+<GATE>
+STOP. If graphify install or graph build was offered, wait for the user's response before proceeding. Graph data enriches Steps 3-9 — loading it now saves significant tokens in later steps.
+</GATE>
+
+### Step 3: Map Project Structure
+
+Examine the directory layout and identify:
+
+- **Root structure**: What lives at the top level? Configuration files, source directories, documentation.
+- **Source organization**: Is it organized by feature, by layer, by module, or mixed?
+- **Entry points**: Where does execution start? (main files, index files, route definitions, CLI entry points)
+- **Configuration**: Build config, environment config, deployment config locations.
+- **Test structure**: Where do tests live? Colocated with source? Separate directory? Both?
+- **Generated/vendored code**: Identify directories that are not hand-written (node_modules, vendor, dist, build).
+
+Output a tree overview, excluding generated directories:
+
+```
+project/
+  src/
+    api/          -- REST API layer (Express routes)
+    services/     -- Business logic
+    models/       -- Database models (Prisma)
+    utils/        -- Shared utilities
+  tests/
+    unit/         -- Unit tests (Jest)
+    integration/  -- Integration tests
+  config/         -- Environment configuration
+  scripts/        -- Build and deploy scripts
+```
+
+### Step 4: Identify Technology Stack
+
+Catalog the technology choices by reading configuration files:
+
+| Category | What to Check | Files to Read |
+|---|---|---|
+| **Language** | Primary and secondary languages | File extensions, config files |
+| **Framework** | Web framework, ORM, test runner | package.json, requirements.txt, go.mod, Cargo.toml |
+| **Database** | Type, ORM, migration tool | Config files, schema files, docker-compose |
+| **Build tools** | Bundler, compiler, task runner | webpack.config, tsconfig, Makefile, build.gradle |
+| **CI/CD** | Pipeline configuration | .github/workflows, .gitlab-ci.yml, Jenkinsfile |
+| **Infrastructure** | Container, orchestration, cloud | Dockerfile, docker-compose, terraform, k8s manifests |
+| **Package manager** | npm, yarn, pnpm, pip, cargo | Lock files (package-lock.json, yarn.lock, etc.) |
+
+Note version constraints where visible (package.json engines, .python-version, .node-version, .tool-versions).
+
+### Step 5: Analyze Code Patterns
+
+Examine actual source files to identify the patterns in use. For each pattern, cite a specific file as an example:
+
+**Architecture patterns:**
+- Layered? (controller -> service -> repository)
+- Domain-driven? (bounded contexts, aggregates)
+- Event-driven? (event bus, pub/sub, message queues)
+- Microservices? Monolith? Modular monolith?
+
+**API patterns:**
+- REST? GraphQL? gRPC? Mixed?
+- How are routes defined? (decorators, file-based routing, explicit registration)
+- How are request/response types defined? (TypeScript interfaces, Pydantic models, protobuf)
+- How is authentication handled?
+- How is authorization handled?
+
+**State management:**
+- Server-side: How is state stored? (database, cache, session, in-memory)
+- Client-side: What state management library? (Redux, Zustand, Context, signals)
+
+**Error handling:**
+- How are errors created? (custom error classes, error codes, plain strings)
+- How are errors propagated? (throw/catch, Result types, error callbacks)
+- How are errors reported to users? (error responses, toast notifications, error boundaries)
+- Is there a centralized error handler?
+
+**Data validation:**
+- Where does validation happen? (API layer, service layer, both)
+- What validation library? (Zod, Joi, class-validator, Pydantic, hand-written)
+- How are validation errors returned to callers?
+
+**Logging and observability:**
+- What logging library? What log levels?
+- Is there structured logging?
+- Any tracing or metrics?
+
+### Step 6: Map Conventions
+
+Document the conventions that new code MUST follow to maintain consistency:
+
+**Naming conventions:**
+- File naming: camelCase, kebab-case, PascalCase, snake_case?
+- Variable naming: camelCase for variables, SCREAMING_CASE for constants?
+- Function naming: verb-first? (getUser, createOrder, handleSubmit)
+- Component naming: PascalCase? Matches filename?
+- Test naming: describe/it style? test_ prefix? What pattern?
+
+**File organization:**
+- One class/component per file? Or multiple?
+- Index files for re-exports? Barrel pattern?
+- Where do types/interfaces live? Colocated or centralized?
+- Where do constants live?
+
+**Import patterns:**
+- Absolute imports? Relative imports? Path aliases?
+- Import ordering convention? (external, internal, relative)
+- Named vs default exports?
+
+**Code style:**
+- Is there a linter config? (.eslintrc, .flake8, clippy.toml)
+- Is there a formatter config? (.prettierrc, black config, rustfmt.toml)
+- Max line length? Indentation style?
+
+**Component patterns** (if frontend):
+- Functional or class components?
+- Props interface naming? (Props suffix, I prefix)
+- Hook patterns? Custom hooks for logic?
+- Styling approach? (CSS modules, styled-components, Tailwind, inline)
+
+### Step 7: Trace Dependency Chains
+
+For the area being modified, map what depends on it and what it depends on:
+
+```
+[files that import from the target area]
+        |
+        v
+   [TARGET AREA]
+        |
+        v
+[files/services the target area depends on]
+```
+
+Identify:
+- **Direct dependents**: Files that import from the target area
+- **Direct dependencies**: Files/services the target area imports or calls
+- **Transitive risks**: Changes that could cascade (shared types, common utilities, database schema)
+- **External dependencies**: Third-party libraries used in this area, with version info
+
+Flag any circular dependencies discovered during this analysis.
+
+### Step 8: Assess Test Coverage
+
+Examine the test infrastructure:
+
+- **Test framework**: Which runner? Configuration?
+- **Test types present**: Unit? Integration? E2E? None?
+- **Coverage**: If coverage tools are configured, check existing reports. If not, note the gap.
+- **Test quality indicators**:
+  - Do tests use real assertions or just check "does not throw"?
+  - Are there integration tests that hit real services/databases or only mocks?
+  - Is there E2E coverage for critical paths?
+- **Testing gaps in the target area**: List files or modules with no test coverage.
+- **Test patterns**: How are tests structured? Setup/teardown patterns? Factory patterns? Fixture approach?
+
+### Step 9: Flag Risks
+
+Identify potential problems that could affect the planned changes:
+
+| Risk Category | What to Look For |
+|---|---|
+| **Tight coupling** | God objects, circular imports, shared mutable state |
+| **Missing tests** | Areas with zero coverage that will be modified |
+| **Tech debt** | TODO comments, deprecated API usage, workarounds with explanatory comments |
+| **Security concerns** | Hardcoded secrets, SQL concatenation, missing input validation |
+| **Performance concerns** | N+1 queries, missing pagination, unbounded loops, no caching |
+| **Fragile areas** | Files with high churn (many recent commits), merge conflict hotspots |
+| **Stale dependencies** | Outdated packages with known vulnerabilities |
+| **Missing documentation** | Complex logic with no comments or docs |
+
+For each risk, rate severity:
+
+- **High**: Will likely cause problems during this change
+- **Medium**: Could cause problems, should be addressed
+- **Low**: Worth noting but unlikely to affect current work
+
+### Step 9.5: Codex Verify
+
+Check the mode recorded at Step 1.5. If **Verify** was selected, dispatch Codex to review the analysis for structural gaps, missed risks, and mischaracterized patterns. Merge findings into a "Second Opinion" section of the report. If **Takeover** was selected, skip this step (Codex already ran the analysis). If **Skip**, do nothing. Do NOT re-run the consent flow. See **Codex Integration** section below for full details.
+
+### Step 10: Write Analysis Report
+
+Write the complete analysis to `.forge/work/{type}/{name}/codebase-analysis.md`.
+
+The report MUST include these sections:
+
+```markdown
+# Codebase Analysis: {feature-name}
+
+## Analysis Scope
+{What was analyzed and why}
+
+## Project Structure
+{Directory tree with annotations}
+
+## Technology Stack
+{Table of technologies with versions}
+
+## Code Patterns
+### Architecture
+{Architectural pattern with examples}
+
+### API Style
+{How APIs are built with examples}
+
+### State Management
+{How state is handled}
+
+### Error Handling
+{Error handling approach with examples}
+
+### Data Validation
+{Validation approach}
+
+## Conventions to Follow
+### Naming
+{Naming conventions with examples}
+
+### File Organization
+{How files are organized}
+
+### Import Style
+{Import patterns}
+
+### Code Style
+{Linter/formatter settings, style patterns}
+
+## Dependency Map
+{Dependency diagram for the target area}
+
+## Test Assessment
+{Test infrastructure, coverage, gaps}
+
+## Risks
+{Categorized risk table with severity}
+
+## Recommendations
+{Suggestions for the upcoming work based on findings}
+```
+
+### Step 11: Update Feature Manifest
+
+After writing the report, update `.forge/work/{type}/{name}/manifest.yaml`:
+
+```yaml
+artifacts:
+  codebase-analysis:
+    path: codebase-analysis.md
+    status: complete
+    completed_at: YYYY-MM-DD
+    scope: targeted | full
+```
+
+---
+
+## Key Rules
+
+1. **Read the actual code.** Do not guess patterns from file names alone. Open files, read implementations, cite specific examples.
+2. **Follow existing patterns.** The analysis report tells future skills what conventions to follow. If the codebase uses snake_case, do not propose camelCase.
+3. **Scope appropriately.** Full project analysis for greenfield-adjacent work. Targeted analysis for small changes. Do not spend 30 minutes analyzing a codebase for a one-line fix.
+4. **Cite specific files.** Every pattern claim must reference at least one file as evidence. "The project uses Express" is weak. "The project uses Express -- see `src/api/routes/users.ts` line 15" is strong.
+5. **Flag, do not fix.** This skill identifies problems. It does not solve them. Fixes happen during planning and implementation.
+6. **Update for every feature.** Even if a codebase analysis exists from a prior feature, run a fresh targeted analysis for the new feature area. Codebases change.
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Is Wrong | What To Do Instead |
+|---|---|---|
+| **Assuming patterns from the framework** | "It's React so they must use hooks" -- maybe they don't | Read the code. Verify. |
+| **Skipping dependency tracing** | Changes cascade through imports you didn't check | Trace at least one level of dependencies |
+| **Ignoring test gaps** | Untested code is unknown code | Flag missing coverage explicitly |
+| **Over-analyzing stable areas** | Time spent on code that won't change is wasted | Focus on the area being modified plus its neighbors |
+| **Listing tools without checking versions** | "Uses TypeScript" is less useful than "Uses TypeScript 5.3 with strict mode" | Check config files for version info |
+
+---
+
+## Special Cases
+
+### Monorepo Analysis
+
+If the project is a monorepo:
+1. Identify the package/workspace structure
+2. Determine which package(s) will be affected
+3. Map cross-package dependencies
+4. Note shared tooling configuration
+
+### No Existing Tests
+
+If the project has no test infrastructure:
+1. Note this as a HIGH risk
+2. Identify the test runner the project would naturally use (based on stack)
+3. Flag that test setup will be an extra task during planning
+
+### Legacy Codebase
+
+If the codebase has significant tech debt:
+1. Separate "tech debt to address now" from "tech debt to leave alone"
+2. Only flag debt that intersects with the planned changes
+3. Suggest incremental improvements, not full rewrites
+
+---
+
+## Graphify Context 
+**Protocol:** `protocols/graphify.md` | **Guard:** Step 2 of this skill's checklist.
+
+**How graph data maps to this skill's output:**
+- **God nodes** → list as critical components in Project Structure and Risks sections
+- **Communities (top 20 by cohesion)** → map to subsystems / bounded contexts in Architecture section
+- **EXTRACTED edges** → trusted, cite directly as dependencies in Dependency Map
+- **INFERRED edges** → flag as hypotheses, verify against actual imports before reporting
+- **AMBIGUOUS edges** → add to Risks section as investigation targets
+
+**CLI queries** (if CLI available and graph exists):
+- `graphify query "what are the main subsystems" --budget 2000 --graph graphify-out/graph.json`
+- `graphify query "what are the cross-cutting concerns" --budget 1500 --graph graphify-out/graph.json`
+- `graphify explain "<god node>" --graph graphify-out/graph.json` — for each god node
+
+**Codex bridge:** Graph-enriched analysis feeds into the Codex verify step below. Pass god nodes, community boundaries, and edge confidence data as context.
+
+---
+
+## Codex Integration
+**Modes:** Verify or Takeover | **Protocol:** `protocols/codex.md`
+
+- **Verify:** Claude analyzes the codebase, Codex reviews for gaps.
+- **Takeover:** Codex analyzes the codebase, Claude reviews the report.
+
+**When:** After the architect subagent produces the codebase analysis report (enriched by graph context if available).
+
+**Context to pass:**
+- Path to `codebase-analysis.md`
+- Path to source directories identified in the analysis
+- Path to `graphify-out/graph.json` and `GRAPH_REPORT.md` (if present)
+
+**What Codex reviews:**
+- Structural gaps the analysis missed (unused exports, disconnected modules, dead code)
+- Dependency risks not flagged (circular imports, version mismatches)
+- Architecture patterns the analysis may have mischaracterized
+
+**Prompt focus:** "Review this codebase analysis for structural gaps, missed risks, and mischaracterized patterns. Focus on what the analysis MISSED, not what it got right."
+
+**Presentation:** Merge Codex findings into the analysis report under a "Second Opinion" section. Flag disagreements with Claude's assessment.
+
+---
+
+## Transition
+
+After the analysis is complete:
+
+> "Codebase analysis complete and written to `.forge/work/{type}/{name}/codebase-analysis.md`. Key findings:
+>
+> - **Architecture**: {one line summary}
+> - **Conventions**: {key convention to follow}
+> - **Risks**: {N} high, {N} medium, {N} low
+>
+> Ready to proceed to brainstorming. I'll use the plan-brainstorm skill to explore approaches, referencing the patterns and conventions identified here."
+
+Invoke `plan-brainstorm` as the next step.