analyze-project

Files (1)

• SKILL.md

SKILL.md (first lines)

# Project Analysis (Zoom Out)

Perform a high-level analysis of this project. Follow the procedural workflow below;
use the rubric sections as reference when interpreting findings.

## Ground rules

- Reproduce before reporting — read the actual files and run the tooling; never assert
  a finding based on file names, directory shapes, or vibes alone.
- Verify catalog-like claims mechanically — if a claim implies "all N of X", script the
  check rather than eyeballing a sample.
- Mark anything you couldn't verify as "unverified"; never guess or extrapolate.
- This is an assessment only: no code changes, no pushes, no triggering workflows or
  releases.
- Honor the target repo's standing context file when present (see step 0).

## Usage

When asked to analyze project health:

### 0. Load repo context

At start, read the target repo's `AGENTS.md` and/or `CLAUDE.md` if present.
**Precedence:** `AGENTS.md` is authoritative when both exist — do not also
apply conflicting `CLAUDE.md` instructions; if only one exists, use that
file; if both conflict in a blocking way, stop and ask. Treat house
standards, operating agreement, and standing constraints in the chosen file
as **binding** for this assessment — including safety limits such as no paid
LLM API calls or local-only storage. See the `stand-general` skill's
**Per-repo agent context** section for the expected file shape. If neither
file exists, continue with chat instructions and `stand-*` skills only.

### 1. Map structure

Understand layout and entry points:

```bash
find . -maxdepth 3 -type f \( -name '*.py' -o -name '*.ts' -o -name '*.rs' -o -name 'Cargo.toml' -o -name 'package.json' -o -name 'pyproject.toml' \) | head -80
tree -L 3 -I 'node_modules|target|.venv|dist|build|__pycache__|.git' 2>/dev/null || find . -maxdepth 3 -type d | head -60
```

Note: source roots, module boundaries, config locations, and test directories.

### 2. Check CI/CD

Inspect automation and pipeline coverage:

```bash
ls -la .github/workflows/ 2>/dev/null
rg -l 'lint|test|build|deploy' .github/workflows/
rg -n --hidden "uses:.*@[0-9a-f]{40}\b" .github/workflows || echo "No SHA-pinned actions found"
```

Verify lint, test, and deploy stages exist; check for pinned action SHAs and reproducible
builds. Then go beyond presence: is CI validating what actually matters, or just
linting? Look for conditional skips (`if: ... == ''`, path filters that silently
no-op a job) and for test suites that exist in the repo but never run in any
workflow — CI claiming a check happens is not the same as it executing.

### 3. Dependency health

Confirm lock files and manifest consistency:

```bash
ls -1 *lock* uv.lock bun.lockb Cargo.lock package-lock.json poetry.lock Pipfile.lock 2>/dev/null
rg -n 'version|dependencies' pyproject.toml package.json Cargo.toml | head -30
```

Flag missing lock files, unpinned versions, or stale dependency patterns.

### 4. README and docs check

Assess onboarding and API documentation:

```bash
test -f README.md && head -80 README.md
find . -maxdepth 2 \( -name '*.md' -o -name 'docs' -type d \) | head -20
rg -l 'TODO|FIXME|TBD' README.md docs/
```

Check for setup instructions, contribution guide, and documented public APIs.

### 5. Hardcoded config search

Find scattered or environment-specific values in source:

```bash
rg -n '(localhost|127\.0\.0\.1|0\.0\.0\.0|hardcoded|FIXME.*config)' --glob '!*.{lock,sum,md}'
rg -n '(API_URL|BASE_URL|DATABASE_URL)\s*=\s*["\x27]' --glob '!*.example' --glob '!*.env*'
```

Evaluate against externalized configuration expectations.

### 6. Coupling and circular dependencies

Assess module boundaries (adapt to language):

```bash
# Python import graph (rough)
rg -n '^from |^import ' --type py | head -50

# TypeScript/JavaScript cross-imports
rg -n "^import .* from ['\"]\.\./" -t ts -t js | head -50

# Rust crate modules
rg -n '^mod |^pub mod ' -t rust | head -30
```

Look for deep cross-package imports, god modules, and circular import chains.

### 7. Backlog, PR state, and release discipline

Check the project against its own tracking, not just its code:

```bash
gh pr list --state open
gh issue list --state open
gh pr list --state merged --limit 20
```

From lgtm-hq/ai-skills, MIT.

More from lgtm-hq/ai-skills