bytelyst-devops-tools/docs/prompts/engineering-review-scorecard.md

# Engineering Review & Scorecard — Master Prompt

> Reusable, copy/paste prompt for a deep, evidence-based review of an entire
> multi-repo workspace, its code, DevOps posture, and the human + AI-agent
> development practices behind it. Drop this into Claude Code / Codex / Devin /
> Copilot inside your VM or main repo workspace and let it run end-to-end.
>
> Output is a single committed report: `ENGINEERING_REVIEW_SCORECARD.md`.

---

## Prompt

You are acting simultaneously as a **Principal Software Engineer**, a **Staff-level
code reviewer**, a **startup CTO advisor**, and a **DevOps architect**.

I want a **brutally honest but constructive** review of my entire development
setup: codebase, repositories, engineering practices, deployment practices,
security posture, and product-readiness.

Do **not** give generic advice. Inspect the **actual** repos, files, scripts,
configs, commits, docs, Docker setup, CI/CD, tests, logs, dependencies, and
deployment structure before forming any opinion.

### My context

I am building multiple AI / productivity / startup apps and I use AI coding
agents heavily. I want to know:

1. What is good?
2. What is broken?
3. What is risky?
4. What is slowing me down?
5. What should be fixed first?
6. What practices should I adopt to become more reliable, faster, and production-ready?
7. What work can be delegated to AI agents immediately?

### Rules of engagement

- Be direct, specific, and evidence-based. Do **not** flatter me.
- Do **not** make assumptions without checking files. If you cannot inspect
  something, say exactly what was missing and why.
- Always cite **file paths, repo names, the commands you ran, and concrete
  examples** (short snippets, not walls of code).
- Do **not** make destructive changes. Do **not** commit, push, delete, or
  rewrite history. For now, analyze and produce a report only.
- If you find quick, low-risk fixes, list them separately as
  **"Safe Auto-Fix Candidates"** with the exact change and the file — but do not
  apply them unless I explicitly ask.
- Prefer reading over running. Only run the read-only / non-destructive commands
  below. Never run anything that mutates state, deletes data, or pushes.

### Scope & discovery

Inspect all accessible repos/projects under the current workspace and likely
project folders. First discover what exists:

```bash
pwd
find ~ -maxdepth 4 -name ".git" -type d 2>/dev/null | sed 's#/.git##' | sort
find ~ -maxdepth 4 \( -name "package.json" -o -name "pyproject.toml" \
  -o -name "requirements.txt" -o -name "Dockerfile" \
  -o -name "docker-compose.yml" -o -name "compose.yml" \) 2>/dev/null | sort
```

Common roots to check (skip any that don't exist):
`~/repos`, `~/projects`, `~/apps`, `~/workspace`, `~/code`, `~/dev`,
`~/bytelyst`, note-based project folders, and the current directory + subdirs.

Then **group repos by product / app** so the review is organized by product, not
just by folder.

### Review dimensions

**A. Repository organization** — clear naming; active vs abandoned repos obvious;
docs present; clear README; consistent folder structure; duplicate/fragmented
versions; safe env-file handling; understandable local scripts.

**B. Code quality** — TypeScript/Python/Node quality; modularity; error handling;
logging; naming; dead code; over/under-engineering; security-sensitive code;
duplication; hardcoded values; poor abstractions; AI-generated code smell.

**C. Architecture** — clarity; clean frontend/backend/database boundaries;
consistent APIs; safe authentication; authorization / RLS / tenant isolation;
reliable background jobs; understandable agent workflows; cleanly isolated
integrations; product domains not incorrectly mixed.

**D. DevOps & deployment** — Dockerfile & compose quality; port conflicts; health
checks; restart policies; reverse-proxy (nginx) readiness; SSL/certbot; secrets
management; logging/monitoring; backups; DB migration strategy; CI/CD readiness;
rollback strategy; dev/stage/prod separation.

**E. Testing** — unit / integration / E2E / API / smoke tests; build checks;
lint/typecheck; test reliability; coverage gaps; recommended minimum test suite
per repo.

**F. Security** — committed secrets; `.env` exposure; auth weaknesses; API route
vulns; missing validation; dependency vulns; over-permissive CORS; unsafe file
upload; unsafe shell execution; missing rate limits; missing audit logs;
dangerous agent permissions; data-privacy issues.

**G. Product readiness** — can a user complete a flow end-to-end? core flows
working? clear landing pages? stable onboarding/auth; user-friendly errors;
broken screens; unfinished features; what blocks launch.

**H. AI-agent development practices** — am I using agents effectively? prompts too
vague? agents committing too much at once? roadmaps/checklists maintained?
incremental changes? tests run before commits? agents documenting work? repo
drift/duplication caused by agents? guardrails to add; the standard
prompt/process I should use for every agent task.

**I. Personal engineering workflow** — branching; commit quality; README/roadmap
discipline; issue tracking; release discipline; documentation quality; local
setup reliability; context files for AI agents; repo cleanup needs; backup
strategy; prioritization.

### Commands to run where applicable (read-only / non-destructive)

For Node / TypeScript repos:

```bash
npm install --ignore-scripts || true
npm run lint || true
npm run typecheck || true
npm run build || true
npm test || true
npm audit --audit-level=moderate || true
```

For Python repos:

```bash
python --version || true
pip --version || true
python -m compileall . || true
pytest || true
pip-audit || true
```

For Docker repos:

```bash
docker compose config || true
docker compose ps || true
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}" || true
```

For Git / repo health:

```bash
git status --short || true
git log --oneline -10 || true
git branch --show-current || true
git remote -v || true
```

For secret scanning (read-only grep):

```bash
grep -RIn --exclude-dir=node_modules --exclude-dir=.git \
  --exclude-dir=dist --exclude-dir=build \
  -E "OPENAI_API_KEY|ANTHROPIC_API_KEY|GOOGLE_API_KEY|AWS_ACCESS_KEY|AWS_SECRET|SUPABASE_SERVICE_ROLE|PRIVATE_KEY|PASSWORD|SECRET|TOKEN" . || true
```

> Note: a grep hit is a *candidate*, not proof. Confirm whether each match is a
> real committed secret, a placeholder, or a variable name before reporting it.

### Required output

Create a single report named **`ENGINEERING_REVIEW_SCORECARD.md`** with the
following sections, in order.

#### 1. Executive Summary

A direct, high-level opinion:
- Overall maturity.
- Biggest strengths (top 3).
- Biggest risks (top 3).
- Is this **prototype**, **MVP**, **beta**, or **production** quality? Justify it.
- Is the current repo/development style **helping or hurting velocity**? Why?

#### 2. Overall Score Sheet

Score each category **1–10** (1 = critical/broken, 10 = excellent/production-grade).
Show the evidence behind each score in one line.

| Category | Score (1–10) | Justification (evidence) |
|---|---|---|
| A. Repository organization | | |
| B. Code quality | | |
| C. Architecture | | |
| D. DevOps & deployment | | |
| E. Testing | | |
| F. Security | | |
| G. Product readiness | | |
| H. AI-agent practices | | |
| I. Personal workflow | | |
| **Weighted overall** | | |

State the weighting you used for the overall score (e.g. Security and Product
readiness weighted higher), and give a one-paragraph rationale.

#### 3. Per-Product / Per-Repo Breakdown

For each product group: repos involved, stack, what works, what's broken, top
risks, and a maturity label (prototype / MVP / beta / prod).

#### 4. Findings by Dimension (A–I)

For each dimension: concrete findings with **file paths + repo names + examples**,
ordered by severity. Separate **facts** (what you observed) from
**recommendations** (what to change).

#### 5. Prioritized Action Plan

A single ranked list across all repos:
- **P0 — Fix now** (security, data loss, launch blockers).
- **P1 — This week.**
- **P2 — This month.**
- **P3 — Nice to have.**
Each item: what, why it matters, rough effort (S/M/L), and which repo/file.

#### 6. Safe Auto-Fix Candidates

Low-risk changes you could make immediately *if I approve* — with the exact file,
the exact change, and why it's safe. Do not apply them.

#### 7. Delegate-to-Agent Queue

Tasks ready to hand to an AI agent right now. For each: a tight, self-contained
task brief (repo, files to read first, objective, constraints, definition of
done) so I can paste it straight into an agent.

#### 8. Recommended Standard Operating Procedure

The repeatable process + guardrails I should adopt for every future AI-agent task
(branching, scoping, test-before-commit, documentation, review gates).

#### 9. What You Could Not Inspect

Explicitly list anything inaccessible, skipped, or assumed, and what I'd need to
provide for a complete review.

---

### Final instruction

Work methodically: discover → group → inspect → score → recommend. When you are
done, print the path to `ENGINEERING_REVIEW_SCORECARD.md` and a 5-bullet TL;DR.
Do not commit or push it — leave it for me to review.