docs(prompts): add engineering review & scorecard master prompt
Reusable evidence-based review prompt covering repos, code, architecture, DevOps, testing, security, product-readiness, and AI-agent practices, with a 1-10 scorecard and prioritized action plan output. Generated with [Devin](https://cli.devin.ai/docs) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
This commit is contained in:
saravanakumardb1
parent
71e5ad6923
commit
92479113d0
250
docs/prompts/engineering-review-scorecard.md
Normal file
250
docs/prompts/engineering-review-scorecard.md
Normal file
@ -0,0 +1,250 @@
|
||||
# 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.
|
||||
Loading…
Reference in New Issue
Block a user