neat-sdd-discovery

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

Current level: neat_01_discovery/
📄 README.md 3.4 KB
📄 SKILL.md 21.1 KB
SKILL.md

---
name: neat-sdd-discovery
description: Use when starting any project - greenfield (new idea, no codebase) or brownfield (existing codebase as target, context, or learning) - before planning and refinement
---

# Discovery

**Role:** You are a senior software architect who extracts actionable insights from existing codebases and shapes new project ideas into structured briefs — every finding answers "so what?"

## Overview

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

**Core principle:** Discovery, 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 context/learning)
- Using a prototype as knowledge source for a new build (brownfield context)
- Pre-refactoring, migration, or architecture change assessment

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

## Quick Reference

| Step | What |
|------|------|
| 1 | Identify project type: greenfield or brownfield |
| 2 | **Greenfield:** gather idea, materials, technical preferences |
| 3 | **Greenfield:** organize into project brief, save, create PROJECT.md |
| 4 | **Brownfield:** ask for repo, intent (target/context/learning), project name |
| 5 | **Brownfield:** run layered discovery L1-L6, write L0 last |
| 6 | Save output, create/update PROJECT.md (target), offer PDF |
| 7 | Suggest next step: `neat-sdd-dive` or `neat-sdd-explain` |

## 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/<repo-folder>` with `git clone --depth 1`, then use that path
4. **Ask intent:** "What's the role of this repo?"
   - **Target** → this IS the project you're working on. Standard discovery — risks, tech debt, opportunities. **Local repos only** — URL repos cannot be targets (PROJECT.md requires a stable local path).
   - **Context** → provides context for a target project (e.g., prototype, legacy system, devops, internal tool). Discovery framed as "what does the target project need to know?" — interfaces, conventions, constraints.
   - **Learning** → just studying this codebase. Discovery framed as "what can I learn?" — patterns to adopt/avoid. No project association.
   - **URL repos:** Only offer context and learning. Do not offer target.
5. **Project name flow:**
   - **Target** → "What's the project name?" (defaults to repo name). Slugify: lowercase, hyphens, no special characters. Creates `docs/neat_sdd/<project>/`.
   - **Context** → Search for existing projects: glob `docs/neat_sdd/*/` in the current working directory AND `<skill-dir>/../docs/neat_sdd/*/`. If one project exists → join it. If multiple → ask which. If none → "No target discovery found. Run a target discovery first."
   - **Learning** → no project association. Uses repo name as `<project>` for output path. Output always saves to `<skill-dir>/../docs/neat_sdd/<repo-name>/` (never inside the studied repo).
6. **Ask repo name:** "What short name should I use for this repo?" (used in output filename, e.g., `discovery-<repo-name>.md`). Check for existing `discovery-<repo-name>.md` — if collision, warn and ask for a different name.
7. **Ask repo type:** "What type of repo is this?" (free-text, e.g., production, prototype, legacy, devops, internal-tool)
8. **Ask project objectives (target intent only):** "What are the project objectives? What are you trying to achieve with this project?" Context and learning intents skip this step.
9. **Do NOT** analyze the current working directory by default — always confirm the target explicitly
10. **Check for existing discovery:** Glob for `docs/neat_sdd/<project>/discovery-<repo-name>.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>

## 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. **Derive project slug:** lowercase the project name, replace spaces with hyphens, remove special characters (e.g., "My Cool App" → `my-cool-app`). Use this as `<project>` for the output path.
7. **Save** to `docs/neat_sdd/<project>/project-brief.md`
8. **Synthesize project objectives:** From the approved brief's Vision and Requirements, distill 3-7 concrete, actionable project objectives. Present to the user for approval before proceeding. These objectives will be saved to PROJECT.md.
9. **Create PROJECT.md** at the current working directory root. Populate Tech Stack and Architecture from the brief's Technical Decisions table. Items the user left undecided (moved to Open Questions) are omitted. Conventions and Avoid are omitted — these are derived from existing code and will be added when a brownfield discovery is run.

   ```markdown
   <!-- Generated by neat-sdd-discovery. Review and customize. -->
   # Project: <name>

   ## Project Objectives
   - <objective 1>
   - <objective 2>

   ## Tech Stack
   - <from Technical Decisions: Language/Framework, Database/Storage, Key Integrations>

   ## Architecture
   - <from Technical Decisions: Architecture style, Deployment target>

   ## Commands

   - **Test:** "not configured"
   - **Build:** "not configured"
   - **Coverage:** "not configured"

   ## Knowledge Base
   - Project Brief: `docs/neat_sdd/<project>/project-brief.md`
   ```

10. **Update CLAUDE.md:** If CLAUDE.md exists at the project root: append `Read PROJECT.md for project context.` if not already present. Do NOT modify other existing content. If CLAUDE.md does not exist: create it with only `Read PROJECT.md for project context.`

Use TodoWrite to track:

- [ ] Ask project type
- [ ] Ask project name
- [ ] Gather idea and requirements
- [ ] Collect all materials
- [ ] Ask technical preferences
- [ ] Organize project brief
- [ ] Present for approval
- [ ] Derive project slug
- [ ] Save output
- [ ] Synthesize project objectives
- [ ] Create PROJECT.md
- [ ] Update CLAUDE.md

### After Saving (Greenfield)

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

---

## Layered Discovery (brownfield)

Each layer builds on the previous. Do NOT skip or reorder. Within a layer, independent sub-topics (e.g., L2's API endpoints vs data models, L6's test coverage vs tech debt) can be explored with parallel agents to speed up large codebases.

```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 context mode:** Frame as "constraints and interfaces the target project must respect" — what conventions to follow, what integration points exist, what limitations to work around.

**In learning 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 context mode:** Frame top findings as "constraints and context for the target project" — what the target project must integrate with, respect, or work around.

**In learning 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/<project>/discovery-<repo-name>.md`. The project's docs folder location is established by the first target discovery:

- **Target:** `<target-repo>/docs/neat_sdd/<project>/` (target is always a local repo)
- **Context:** saves to the existing project's docs folder (wherever it was established).
- **Learning:** `<skill-dir>/../docs/neat_sdd/<repo-name>/`
- **Greenfield:** `<current-working-dir>/docs/neat_sdd/<project>/`

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 context mode:** Replace "Implications for change" with "Implications for target project" in each section.

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

## Full Mode (first run)

When no previous discovery exists. Run 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/context/learning)
- [ ] Determine project name (target: ask, context: find existing, learning: use repo name)
- [ ] Ask repo name
- [ ] Ask repo type
- [ ] Ask project objectives (target intent only)
- [ ] 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 `discovery-<repo-name>.md` already exists. Update in place — don't rewrite from scratch.

1. **Read existing discovery** and resolve the repo path by matching <repo-name> from the filename discovery-<repo-name>.md to PROJECT.md's Repos table
2. **Detect changes** — use git log on the discovery file to determine the last update date, then git diff and git log since that date 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. **Target intent only:** If L1, L3, or L6 were updated, also refresh the corresponding PROJECT.md sections (Tech Stack, Architecture, Conventions, Avoid). Resolve repo path by matching <repo-name> from the filename discovery-<repo-name>.md to PROJECT.md's Repos table.
7. **Target intent only:** Check `## Project Objectives` in PROJECT.md. If missing, ask: "What are the project objectives? What are you trying to achieve with this project?" If present, show current objectives and ask: "Still accurate, or want to update?" Also ask if any objectives are now achieved — mark achieved objectives as `~~objective~~ Achieved`.

Use TodoWrite to track:

- [ ] Read existing discovery and resolve repo path from PROJECT.md Repos table
- [ ] Detect changes since last discovery date
- [ ] Map changes to affected layers
- [ ] Update affected layers in place
- [ ] Update L0 executive summary
- [ ] Save output
- [ ] Target intent: refresh PROJECT.md if L1/L3/L6 changed
- [ ] Target intent: review/add project objectives

## 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 intent (target/context/learning) | The intent changes discovery framing, project association, and PROJECT.md behavior |
| 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 discovery 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 |
| Saving as `discovery.md` without repo name | Always use `discovery-<repo-name>.md` |
| Creating PROJECT.md for context/learning repos | Target creates PROJECT.md. Context updates repos table only. Learning gets nothing. |
| Using target intent for URL repos | URL repos can only be context or learning — target requires a local path for PROJECT.md |
| Running context discovery without an existing target | Context must join an existing project — run target discovery first |
| Overwriting existing CLAUDE.md content | Only append the `Read PROJECT.md` line if missing |
| Asking objectives for context/learning intents | Objectives are target-only — context and learning intents skip this step |
| Greenfield PROJECT.md missing Tech Stack/Architecture | Populate from the brief's Technical Decisions — undecided items are omitted |
| Greenfield skipping CLAUDE.md update | Greenfield also creates PROJECT.md — update CLAUDE.md the same as brownfield target |
| Context intent on greenfield PROJECT.md with no Repos table | Create the `## Repos` section if it doesn't exist |

## After Saving (brownfield)

1. **Target intent — create/update PROJECT.md:**
   - Locate PROJECT.md at the target project root. If it doesn't exist, create it using the structure below.
   - **Repos table:** Add or update the row for this repo (name, path, URL, type, intent). Extract the git remote URL via `git remote get-url origin`.
   - **Project Objectives:** Populate from the objectives gathered during setup (target intent only).
   - **Tech Stack:** Populate from L1 findings (exact versions from lock files).
   - **Architecture:** Populate from L3 findings (pattern, key structural conventions).
   - **Conventions:** 2-3 key conventions from L1 (project structure, naming, build tools).
   - **Avoid:** 2-3 anti-patterns from L3/L6 (concrete, not generic advice).
   - **Commands:** Detect test/build/coverage commands from the tech stack:
     - `package.json` → `scripts.test`, `scripts.build`, coverage via `--coverage` flag
     - `pyproject.toml` → `pytest`, `coverage run`
     - `Makefile` → `make test`, `make build`
     - `go.mod` → `go test ./...`, `go build ./...`
     - `Cargo.toml` → `cargo test`, `cargo build`
     - Other stacks: `"not configured"` (user configures manually)
     - If `## Commands` already exists, preserve user-customized values. Only fill in commands still set to `"not configured"`.
   - **Knowledge Base:** Add the discovery output path: `- Discovery (<repo-name>): docs/neat_sdd/<project>/discovery-<repo>.md`
   - On subsequent runs for the same project, update existing sections — don't duplicate.

   ```markdown
   <!-- Generated by neat-sdd-discovery. Review and customize. -->
   # Project: <name>

   ## Repos
   | Name | Path | URL | Type | Intent |
   |------|------|-----|------|--------|

   ## Project Objectives
   - <objective 1>
   - <objective 2>

   ## Tech Stack
   - <from L1>

   ## Architecture
   - <from L3>

   ## Conventions
   - <from L1>

   ## Avoid
   - <from L3/L6>

   ## Commands

   - **Test:** <detected or "not configured">
   - **Build:** <detected or "not configured">
   - **Coverage:** <detected or "not configured">

   ## Knowledge Base

   - Discovery (<repo-name>): `docs/neat_sdd/<project>/discovery-<repo>.md`
   ```

   For multi-repo projects (multiple target repos), group Tech Stack, Architecture, Conventions, and Avoid by repo name with sub-headings:

   ```markdown
   ## Tech Stack
   ### holocron-app
   - TypeScript 5.4, React 18
   ### holocron-api
   - Python 3.11, FastAPI
   ```

   Single-repo projects stay flat (no sub-headings). When adding a second target repo to a project that was previously single-repo, restructure the existing flat content into sub-headings under the first repo's name before adding the new repo's sub-heading.

2. **Target intent — update CLAUDE.md:**
   - If CLAUDE.md exists at the project root: append `Read PROJECT.md for project context.` if not already present. Do NOT modify other existing content. If CLAUDE.md does not exist: create it with only `Read PROJECT.md for project context.`

3. **Context intent — update PROJECT.md repos table only:**
   - Add this repo to the repos table in PROJECT.md (name, path, URL, type, intent). If the `## Repos` section doesn't exist (e.g., greenfield-created PROJECT.md), create it above `## Project Objectives`.
   - Do NOT update Tech Stack, Architecture, Conventions, or Avoid — those reflect target repos only.

4. **Learning intent:** Skip all PROJECT.md and CLAUDE.md steps.

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

Directory Structure

SKILL.md

Report

Notice
