create-codebase-analysis

Create Codebase Analysis

Analyzes the existing internal code and architecture that a feature will rely on, change, or replace, and assesses each relevant part's changeability before the design is committed. The goal is to know the terrain before specifying how to change it: what exists today, how it is coupled, what can be touched safely, and what must stay stable.

This is the internal counterpart to create-existing-solutions. create-existing-solutions surveys external prior art (libraries, OSS, products) and checks for cheap internal reuse. This skill goes deeper into the internal architecture you are about to modify: it maps components, coupling, and blast radius, and decides a change disposition for each part (reuse as-is, extend, refactor, or replace).

Prerequisites

• Apply the shared SDLC conventions in skills/sdlc/references/shared.md.
• If no argument is provided, locate the feature directory under .sdlc/features/ whose frontmatter issue field references $ISSUE_NUMBER.
• .sdlc/features/N-<slug>/requirements.md (must have passed review with findings verdict approved), or a requirements document provided in context or as a file path ($1)
• .sdlc/features/N-<slug>/existing-solutions.md (optional): carry forward any internal reuse candidates it already identified so they are not re-discovered
• Read any files present under .sdlc/context/ (project-overview.md, architecture.md, conventions.md, vocabulary.md, schema.dbml) for project-level context
• Apply any artifact style rules found in conventions.md to the produced document

Steps

1. Read the requirements document and extract the functional and non-functional requirements that imply changes to existing code.
2. Read .sdlc/context/architecture.md (if present) to ground the analysis in the documented system topology, and read the existing solutions survey if one was produced.
3. Determine the analysis scope: which parts of the codebase this feature will touch, integrate with, or replace. Trace inward from the requirements to concrete modules, services, data stores, and interfaces.
4. Locate the relevant code by searching the codebase. Record the entry points used (queries, paths) so the search is auditable.
5. For each relevant component, capture its name, location (file or module path), current responsibility, and how the feature interacts with it (reads, writes, extends, replaces).
6. Map dependencies and coupling between the relevant components and any external systems as a Mermaid flowchart LR with one node per component and class assignments matching the change dispositions (reuse / extend / refactor / replace). Call out shared state, synchronous vs. asynchronous boundaries, and the blast radius of changing each part in the accompanying prose. The diagram makes unintended coupling visible at a glance; the prose carries what the diagram cannot.
7. For each component, decide a change disposition and justify it:
   • Reuse as-is — the component already does what is needed; do not modify it.
   • Extend — add to the component along its existing seams (new method, new config, new consumer) without altering current behavior.
   • Refactor — restructure the component's internals to accept the change, while preserving its observable behavior.
   • Replace — supersede the component (or a path through it) with a new implementation.
8. For every Refactor or Replace disposition, outline migration and impact: the path from current to target behavior, backward compatibility, rollout strategy, what else breaks, and how to de-risk (feature flag, dual-run, shadow comparison).
9. Record assumptions about existing behavior that the analysis relies on but has not fully verified. Promote any that carry meaningful risk via /create-assumption, and log architectural choices via /create-decision.
10. Flag open questions where the changeability of a part cannot be decided without more investigation.
11. Write the output to .sdlc/features/N-<slug>/codebase-analysis.md.