neat-code-analysis

Category: Development & Coding | Uploader: neatbuild | Downloads: 0 | Version: v1.0（Latest）
Use when starting any project - greenfield (new idea, no codebase) or brownfield (existing codebase to work on or use as reference) - before planning and refinement
Changelog: Source: GitHub https://github.com/neatbuild/neat-sdd
Directory Structure

Current level: neat_01_analysis/
📄 README.md 2.7 KB
📄 SKILL.md 11.0 KB
SKILL.md

---
name: neat-code-analysis
description: Use when starting any project - greenfield (new idea, no codebase) or brownfield (existing codebase to work on or use as reference) - before planning and refinement
---

# Code Analysis

**Role:** For brownfield: you are a senior software architect who extracts actionable insights from codebases — every finding answers "so what?" For greenfield: you are a senior business analyst who shapes ideas into structured project briefs.

## Overview

Structured knowledge extraction for any project type. For brownfield: layered codebase analysis (L0-L6). For greenfield: idea and materials gathering into a project brief.

**Core principle:** Analysis, not documentation. Every section must answer "so what?"

## When to Use

- Starting a new project from scratch (greenfield)
- Dropped into an unfamiliar codebase (brownfield)
- Rebuilding a system with a different tech stack (brownfield reference)
- Using a prototype as knowledge source for a new build (brownfield reference)
- Pre-refactoring, migration, or architecture change assessment

**Not for:** Single-file review, debugging a specific bug.

## Setup (mandatory first step)

1. **Ask project type:** "Is this a greenfield project (new, no existing codebase) or brownfield (existing codebase)?"

### If Greenfield

Proceed to **Greenfield Mode** below.

### If Brownfield

1. **Ask for repo:** "What codebase should I analyze? Provide a local path or GitHub URL."
2. **If local path:** verify it exists and contains code (check for README, package manifests, or source directories)
3. **If GitHub URL:** clone to `/tmp/<project>` with `git clone --depth 1`, then use that path
4. **Ask intent:** "Are you working on this repo, or using it as a reference for a new build?"
   - **Target** → standard analysis focusing on the repo's current state, tech debt, and improvement opportunities
   - **Reference** → analysis focused on extracting domain logic, architecture patterns, and lessons to carry forward
5. **Do NOT** analyze the current working directory by default — always confirm the target explicitly
6. **Check for existing analysis:** Glob for `docs/neat_sdd_output/<project>/code-analysis.md`. If found → incremental mode. If not → full mode.

## Greenfield Mode

When building something new with no existing codebase.

1. **Ask for the idea:** "Describe what you want to build — the problem it solves, who it's for, and any key requirements."
2. **Gather materials:** "Do you have any supporting materials? Docs, sketches, reference URLs, example apps, API docs, wireframes — anything relevant." Collect everything the user provides.
3. **Ask technical preferences:** "Do you have preferences or constraints on any of these? Skip any you're unsure about — I'll note them as open questions."
   - Language / framework (e.g., TypeScript + Next.js, Python + FastAPI)
   - Database / storage (e.g., PostgreSQL, SQLite, S3)
   - Architecture style (e.g., monolith, microservices, serverless)
   - Deployment target (e.g., Vercel, AWS, self-hosted)
   - Key integrations (e.g., Stripe, Auth0, SendGrid)
4. **Organize into a project brief** (incorporating answers from steps 1-3):

### Project Brief Structure

```text
# Project Brief: <Project Name>

> Generated: YYYY-MM-DD | Project: <project>

## Vision
One-paragraph summary of what this is and why it matters.

## Target Users
Who will use this and what problems it solves for them.

## Requirements
Functional and non-functional requirements gathered from the user.

## Materials
Inventory of all provided materials with summaries of key content from each.

## Constraints
Timeline, budget, team size, or other non-technical constraints mentioned.

## Technical Decisions
| Area | Decision | Rationale |
|------|----------|-----------|
| Language / Framework | e.g., TypeScript + Next.js | User preference / requirement |
| Database / Storage | e.g., PostgreSQL | ... |
| Architecture | e.g., Monolith | ... |
| Deployment | e.g., Vercel | ... |
| Key Integrations | e.g., Stripe, Auth0 | ... |

Items the user skipped or was unsure about → move to Open Questions.

## Open Questions
Gaps, ambiguities, or decisions that still need to be made — including any technical areas left undecided.
```

5. **Present summary** to user. Wait for approval.
6. **Save** to `docs/neat_sdd_output/<project>/project-brief.md`

Use TodoWrite to track:

- [ ] Ask project type
- [ ] Gather idea and requirements
- [ ] Collect all materials
- [ ] Ask technical preferences
- [ ] Organize project brief
- [ ] Present for approval
- [ ] Save output

### After Saving (Greenfield)

1. Offer PDF: "Project brief saved. Want a PDF version?" — if yes, invoke `neat-pdf`
2. Suggest next step: "You can use `/neat-planning` to generate a prioritized plan from this brief."

---

## Layered Analysis (brownfield)

Each layer builds on the previous. Do NOT skip or reorder.

```mermaid
graph TD
  L1[L1: Foundation] --> L2[L2: Interfaces]
  L2 --> L3[L3: Architecture]
  L3 --> L4[L4: Flows]
  L4 --> L5[L5: Behavior]
  L5 --> L6[L6: Health]
  L6 --> L0[L0: Executive Summary - write LAST, place FIRST]
```

### L1: Foundation

Tech stack (exact versions from lock files), dependencies (categorized), project structure (conventions not file trees — max 30 lines), build tools, mono/multi-repo layout.

### L2: Interfaces

API endpoints (method, path, auth, purpose), data models/schemas, event interfaces, configuration surface (env vars, config files, feature flags), external integration points (service, protocol, failure impact).

### L3: Architecture

Architecture pattern, component relationship map (required — use Mermaid to show components, communication protocols, data flow direction, shared resources), deployment topology, cross-cutting concerns (auth, error handling, logging, observability), active vs deprecated components.

Identify architectural anti-patterns (monolith where inappropriate, circular dependencies, tight coupling, distributed monolith).

### L4: Flows

Primary user-facing flow end-to-end, auth flow, error/recovery flows (minimum 3 flows total). Use Mermaid sequence diagrams for complex flows. State management: what stores state, what persists it, how it syncs — both frontend and backend.

For each flow, identify 2-3 edge cases (timeouts, partial failures, race conditions, invalid state) with severity (high/medium/low).

### L5: Behavior

User journeys, business workflows, domain concepts, permissions model, localization. Note any domain-level edge cases not covered by L4 (business rule conflicts, permission boundaries, unusual but valid user behavior).

### L6: Health

Test coverage (what IS and ISN'T tested), code quality signals, technical debt (prioritized: high/medium/low), dead code, security posture, dependency health, documentation state.

Identify code-level anti-patterns (god classes/files, hardcoded values, copy-paste duplication, long methods/functions).

**Be honest.** This section surfaces risks, not praise.

**In reference mode:** Frame as "patterns to adopt/avoid" — focus on what worked well and what to leave behind.

### L0: Executive Summary (write last, place first)

- System purpose (one sentence)
- Architecture style (one sentence)
- At-a-glance stats table:

| Category | Stat |
|----------|------|
| **Scale** | Lines of code (or files), number of dependencies |
| **Complexity** | Number of components/services, number of API endpoints |
| **Health** | Test coverage %, dependency freshness (outdated count, known vulnerabilities) |

- Top 5 findings
- Top risks
- Component map (Mermaid diagram)

**In reference mode:** Frame top findings as "lessons for the new build" — what to carry forward and what to change.

## Output Format

Save to `docs/neat_sdd_output/<project>/code-analysis.md` in the target project's working directory. First line after title:

```text
> Generated: YYYY-MM-DD | Repo: /path/or/url
```

Each section follows:

```text
## L[n]: Section Title

**Key findings:** 3-5 bullets

[Content with tables, Mermaid diagrams, structured data]

**Implications for change:** What this means for modifications
```

**In reference mode:** Replace "Implications for change" with "Lessons for new build" in each section.

## Full Mode (first run)

When no previous analysis exists. Analyze everything L1-L6, write L0 last.

Use TodoWrite to track:

- [ ] Ask project type (greenfield/brownfield)
- [ ] Ask for target repo (local path or GitHub URL)
- [ ] Ask intent (target/reference)
- [ ] Read project root files (README, config, package manifests)
- [ ] Identify all sub-projects/components
- [ ] L1-L6 in order
- [ ] L0 last
- [ ] Save output

## Incremental Mode (subsequent runs)

When `code-analysis.md` already exists. Update in place — don't rewrite from scratch.

1. **Read existing analysis** and extract the repo path from the header
2. **Detect changes** — use `git diff` and `git log` since the analysis date (from the `> Generated:` header) to identify changed files and areas
3. **Scope the update** — map changed files to affected layers:
   - New/removed dependencies → L1
   - Changed APIs, schemas, config → L2
   - Structural changes (new components, moved modules) → L3
   - Changed flows or state management → L4
   - New/changed user journeys or business rules → L5
   - Test changes, new debt, security changes → L6
4. **Update only affected layers** — edit the existing sections in place. Unchanged layers stay as-is.
5. **Update L0** — refresh executive summary, stats table, and top findings to reflect current state
6. **Update the `Generated` date** in the header

Use TodoWrite to track:

- [ ] Read existing analysis and extract repo path
- [ ] Detect changes since last analysis date
- [ ] Map changes to affected layers
- [ ] Update affected layers in place
- [ ] Update L0 executive summary
- [ ] Update Generated date and save

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Skipping project type question | Always ask greenfield/brownfield first |
| Analyzing current directory without asking | Always ask for target repo first |
| Not asking target vs reference for brownfield | The intent changes the analysis framing |
| Exhaustive file tree dump | Describe conventions, max 30 lines |
| Only documenting happy path | Trace error and auth flows too |
| Ignoring edge cases | Identify 2-3 edge cases per flow in L4; catch domain-level edge cases in L5 |
| Listing facts without "so what" | End each section with implications |
| Writing L0 first | You don't know what matters until analysis is done |
| Prose instead of structured data | Use tables, Mermaid diagrams, component maps |
| Skipping technical preferences for greenfield | Always ask — undecided items go to Open Questions |
| Putting undecided tech in Technical Decisions | If the user skipped or was unsure, it belongs in Open Questions |

## After Saving (brownfield)

1. Offer PDF: "Analysis saved. Want a PDF version?" — if yes, invoke `neat-pdf` (landscape layout, save PDF to `docs/neat_sdd_output/<project>/pdfs/`, HTML to `docs/neat_sdd_output/<project>/htmls/`)
2. Suggest next step: "You can use `/neat-explain` to ask questions about this codebase, or `/neat-dive` to deep-dive into specific areas."
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
neat-code-analysis

Directory Structure

SKILL.md

Report

Notice
