project-discovery

Project Discovery

Before editing, map the system. Do not propose structural changes without evidence in the repository.

Flow

1. Identify the project type: web app, API, mobile, monorepo or library.
2. Locate entrypoints, configs and build/test/lint scripts.
3. Extract the real stack from manifests and imports, not from assumptions.
4. Map domain folders, layers and boundaries (UI, API, data, auth).
5. List existing patterns: naming, state, errors, tests, CI.
6. List risks: technical debt, critical files, areas without tests.
7. Only then propose the smallest plan aligned with the conventions found.

What to inspect

• Manifests: package.json, pnpm-workspace.yaml, Cargo.toml, Podfile, Package.swift, .xcodeproj
• Frameworks: Next.js, Vite, Expo, SwiftUI, Nest, Express, Prisma
• Routes and entrypoints: app/, pages/, src/main, App.tsx, ContentView
• Data: Prisma/Drizzle schemas, migrations, HTTP clients
• Auth and middlewares
• Tests and CI: *.test.*, Playwright, GitHub Actions
• Environment variables and secrets (without exposing values)

Minimum report

Deliver a short summary:

• Stack and approximate version
• Architecture in 3–6 bullets
• Conventions to respect
• Risk hotspots
• Recommended next step

Rules

• Prefer file evidence over memory of generic patterns.
• If there is a conflict between docs and code, the code wins.
• Do not refactor “in passing” during discovery.
• Preserve the local style; do not impose another architecture without an explicit request. If the user asks for structure: software-architecture.
• In monorepos, declare which package/app is in scope.

Completion criteria

• Stack and entrypoints confirmed
• Main conventions listed
• Risks and critical dependencies identified
• Change plan proportional to the request