# Is This Portfolio Project Worth Showing?

> Run this before adding a project to a CV or a portfolio. The bar is not "does it work" — it is
> **can an interviewer ask "why did you do it that way?" and get an interesting answer.**
>
> See [Projects](/academy/projects/) for briefs built around this standard.

**Project:** _______________  **Date assessed:** _______

## 1. Is it finished?

- [ ] It runs, from a clean checkout, following the README
- [ ] Someone else could run it without asking me anything
- [ ] There is no half-built feature visible in the interface or the code
- [ ] I would be comfortable with an interviewer browsing the whole repository

Small and complete beats ambitious and abandoned, every time. An unfinished project demonstrates
that you do not finish things, which is the opposite of the intended message.

## 2. Does it handle failure?

This is the single strongest signal, and the most commonly missing.

- [ ] It does something sensible when a dependency is unavailable
- [ ] Errors are handled or deliberately propagated, not swallowed
- [ ] It does not lose or corrupt data when it fails partway
- [ ] Bad input produces a clear message rather than a stack trace
- [ ] I have actually tested the above rather than assumed it

**What happens when its main dependency is down?** _______________

A small system that degrades sensibly demonstrates more than a large one that works in the demo.

## 3. Does the README explain decisions?

- [ ] Problem stated in the first paragraph
- [ ] **What I chose, and what I rejected**
- [ ] Trade-offs named honestly
- [ ] What I would do differently now
- [ ] Setup instructions that work
- [ ] Assume the reader gives it ninety seconds

**A section on what went wrong and what I learned:** yes / no

That section is more persuasive than a feature list. It distinguishes people who have operated
systems from people who have only built them.

## 4. Is there a number in it?

- [ ] The project produces a measurement — accuracy, hit rate, latency, cost per operation,
      rollback time
- [ ] That number is in the README
- [ ] I can explain how it was measured
- [ ] I can say what would improve it

**The number:** _______________

A specific figure invites exactly the question you want to be asked, and it signals that you
measured rather than assumed.

## 5. Can I defend it?

Answer out loud. Hesitation here is what the checklist is for.

**Why this approach rather than the obvious alternative?** _______________

**What would break first under ten times the load?** _______________

**What is the worst code in it, and why is it like that?** _______________

**What did I not build, and why?** _______________

- [ ] I can answer all four without notes
- [ ] I used AI assistance and can still explain and defend every decision

> Using AI to build it is normal and fine. If you cannot answer "why this way?" about your own
> project, it is not yours in the sense that counts — and that becomes obvious within two
> follow-up questions.

## 6. Honest scope

- [ ] The description matches what it actually is
- [ ] I have not called it a "platform" if it is a small service
- [ ] I have not implied it is in production if it is not
- [ ] Anything borrowed heavily from a tutorial is acknowledged

Inflated scope invites scrutiny you cannot survive. "A small system that does one thing well and
handles failure" is accurate and attractive.

## Verdict

| | |
|---|---|
| Finished | yes / no |
| Handles failure | yes / no |
| README explains decisions | yes / no |
| Contains a measured number | yes / no |
| I can defend the trade-offs | yes / no |

**Four or five yes — show it.** Two or three — one focused evening on failure handling and the
README usually fixes it. Zero or one — build something smaller and finish it instead.

**Action before I show this:** _______________