---
name: kedarrio/understand-the-project
source: https://app.decimal.ai/s/kedarrio-understand-the-project@1/SKILL.md
source_sha256: 0235ed15ae6c
---

# Understand the Project Skill

## Purpose
Build an accurate, current picture of the project's framework, structure, conventions, and state before making any change. This prevents wrong assumptions, duplicate code, broken conventions, and wasted work.

## When to Use
- At the start of any new task in a repo you haven't inspected recently.
- Before planning a feature, writing code, debugging, or refactoring.
- When the project structure, stack, or conventions are unknown or unclear.
- After a long gap, when the codebase may have changed.

## When Not to Use
- For trivial, isolated tasks where the relevant file and convention are already known and recently confirmed (e.g. fixing a typo in a string you just read).
- When the user explicitly provides full context and the task is scoped to a single already-inspected file.

## Required Inputs
- Access to the project's file tree.
- The task or request that motivates the inspection (helps focus what to look at).

## Assumptions
- The project may use Next.js, Expo Router, Vite, or another framework — do not assume which.
- The project may already deviate from the default architecture rule of thumb (`/app`, `/components`, `/lib`, `/services`, `/db`, `/hooks`, `/store`, `/types`, `/styles`, `/public`). Existing structure wins.
- Package manager (npm/yarn/pnpm/bun) is determined by lockfile, not preference.

## Step-by-Step Workflow
1. **Read root config files**: `package.json`, `tsconfig.json` / `jsconfig.json`, framework config (`next.config.*`, `vite.config.*`, `app.json`/`expo`), `.env.example`, lockfile (determines package manager).
2. **Identify the framework and routing style**: Next.js (App Router vs Pages Router), Expo Router, Vite + React Router, or other. Confirm by checking actual folder layout, not just dependencies.
3. **Map the top-level structure**: list top 2 levels of directories. Note what each top-level folder actually contains vs. the default rule of thumb.
4. **Identify styling approach**: CSS Modules, Tailwind, styled-components, global CSS, etc. — check `package.json` and a sample component.
5. **Identify state management**: look for Redux/Zustand/Jotai/Context/React Query/SWR/etc.
6. **Identify data layer**: how API calls are made (fetch wrappers, service files, server actions, ORMs like Prisma/Drizzle).
7. **Check for existing scripts**: lint, typecheck, test, build commands in `package.json`.
8. **Check for docs**: README, `/docs`, architecture notes, decision records.
9. **Scan for patterns relevant to the current task**: e.g. if the task involves auth, find existing auth code; if it involves a component type, find similar existing components.
10. **Summarize findings internally** (framework, structure, conventions, scripts, relevant existing files) and carry this into the next skill (Clarify, Plan, etc.).

## Rules and Best Practices
- Detect before assuming. Never default to the rule-of-thumb structure if the project already has its own.
- Confirm the package manager from the lockfile (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `bun.lockb`) and never switch it.
- Note the framework's routing convention precisely (e.g. Next.js App Router uses `app/` with `page.tsx`/`layout.tsx`; Expo Router uses file-based routing under `app/`; Vite + React Router uses a router config file).
- Identify at least one existing example of each relevant pattern (component, service call, state usage) before writing new code that follows it.
- Keep this inspection proportional to the task — a full deep audit is not required for small, well-scoped tasks, but the basics (framework, structure, styling, relevant existing files) should always be checked.

## Safety Checks
- Do not modify any files during this skill — it is read-only.
- Do not assume missing context; if critical project details can't be determined from the repo, flag this for the Clarify the Request Skill.

## Validation Checks
- Confirm: framework identified, routing style identified, package manager identified, styling approach identified, state approach identified, relevant existing files for the task identified.
- If any of these can't be determined, note it explicitly rather than guessing.

## Common Mistakes to Avoid
- Assuming the default `/app /components /lib ...` structure without checking.
- Assuming Next.js when the project is Expo Router or Vite (or vice versa).
- Missing an existing similar component/service and creating a duplicate.
- Inspecting too broadly for a tiny task, wasting time before getting to the actual work.
- Trusting `package.json` dependencies alone without confirming actual usage in code.

## Output Rule
Do not invent a custom final response format for this skill. Follow the Global Agent Output and Reporting Skill. Only include skill-specific reporting details when necessary for understanding the completed work.