Project 9 — Spec → AI → Review

“And whatever the man called every living creature, that was its name.” — Genesis 2:19

Chapter: 9 — Pair Programming With AI Due: End of Week 9 Submit: A link to your code — an OnlineGDB project URL or a public GitHub repo URL — containing EventLog.java, EventLogTest.java, spec.txt, review.docx, and prompts.txt. See Coding 1’s online-coding workflow appendix for the Phase 2 submission workflow. Allowed tools: Java 17, JUnit 5, your AI assistant, your eyes, your testing discipline. The new requirement starts here: every prompt you sent the AI lives in prompts.txt. The grader reads it alongside your code.

The Setup

This is your first formal exercise of the senior/junior model. The AI is your fast, willing, sometimes-wrong junior. You are the senior. The whole point of the project is to practice the workflow — spec, prompt, AI output, review, test, document — on a small enough problem that you can do the full cycle in two or three hours.

You will not be graded primarily on whether the code works. You will be graded on whether the process worked: whether your spec was clear, whether your review caught what was wrong, whether your tests are real tests, and whether your prompts.txt honestly shows what happened.

A grader looking at your submission should be able to read your spec, see what you handed the AI, see the AI’s first response, see your review (with the specific things you changed and why), and see the tests that prove the final code does what the spec promised. That is the senior’s deliverable. The code is a byproduct.

Learning Targets

By completing this project, you will demonstrate that you can:

• Write a complete written spec for a small class before writing any code.
• Prompt an AI assistant with that spec and produce usable code from it.
• Read the AI’s output critically and identify at least one substantive issue.
• Write JUnit 5 tests that verify the spec, including at least one test that catches a non-obvious bug.
• Document the entire prompt-and-review cycle in a way another engineer could read and trust.
• Honestly disclose what the AI did and what you did.

If you can do these six things at the end of this week, you’ve shipped a Normal completion. Everything else is Medium and Hard territory.

Normal Tier

Goal: One clean spec-AI-review cycle on a small class.

The class

Implement EventLog — a chronological log of named events grouped by category. You may use the spec sketched in §9.7 of the chapter, or write your own spec for the same class. (If you use the chapter’s spec, your spec.txt should expand it — add more detail, more examples, more edge cases.) A starting-point EventLog.java and the chapter’s EventLogTest.java are available to download.

You may pick a different small class if you prefer (a TaskTracker, a Roster, a PrayerJournal — anything roughly the same size as EventLog). The size guidance: 3–6 public methods, one nested record or supporting type, observable behavior the tests can exercise.

Required deliverables

1. spec.txt — your written specification. Includes:

   • Class name and one-sentence purpose.
   • Public API: every method signature with a Javadoc-style contract (parameters, return value, error behavior, edge cases).
   • At least three concrete examples of input → expected output.
   • At least two invariants the class maintains.

2. EventLog.java (or whatever your class is named) — the implementation. The AI produces the first draft; you finalize it after review.

3. EventLogTest.java — a JUnit 5 test class with at least 8 tests. Tests must include:

   • At least one happy-path test.
   • At least one error-case test (asserts an exception).
   • At least one edge case (empty input, zero, boundary value).
   • At least one invariant test (e.g., a getter doesn’t expose mutable internal state).
   • At least one test you can identify as having caught a bug — or, if your code was clean, a test you can identify as having almost caught a bug.

4. review.docx — your written review of the AI’s output. Includes:

   • The AI’s first response (or a clearly-labeled link/excerpt of it).
   • At least three specific things you changed and why.
   • At least one thing the AI did better than you would have on your own.
   • One paragraph: “Would I have shipped this without review? Why or why not?”

5. prompts.txt — the chronological log of every prompt you sent the AI for this project. Required format:

## Prompt 1 — 2026-05-25 14:32
[the exact text of your prompt]

### Response summary
[1–2 sentences on what came back; full text optional]

### What I did with it
[1 sentence: kept it, tweaked it, asked again, discarded]

---

## Prompt 2 — 2026-05-25 14:39
...

Every prompt. Even the ones you sent and immediately regretted. Especially those.

Grading rubric — Normal (out of 100)

The split is deliberate. Process (spec, review, prompts, tests) is worth 75 points. Code (compiles, passes tests, honors spec) is worth 25. Phase 2 grades the process because the code is half the work and the process is the rest.

Medium Tier (+up to 25% extra credit)

Layer one or both of the following on top of Normal.

M1. Three plausible-but-wrong findings

In review.docx, add a section titled “Plausible But Wrong”. Identify three specific places in the AI’s first output where the code was wrong in a way that would have shipped if you didn’t review. For each:

• Show the AI’s original line(s).
• State precisely what is wrong.
• Show your fix.
• Classify the bug: (a) off-by-one / boundary error, (b) wrong null or empty handling, (c) hallucinated API, (d) inconsistent with the spec, (e) performance trap, or (f) something else (name it).

If the AI’s first output had fewer than three real problems, you may either (a) re-prompt with a deliberately weaker spec to provoke worse output and document that, or (b) honestly say so and identify three almost-problems (places where a slightly worse AI would have made a mistake; explain what would have gone wrong).

This is your first formal practice at code review, the discipline Chapter 11 will make central.

M2. Two-pass refinement

Send the AI’s first response back to the AI with a targeted refinement prompt. (“Here’s the code you produced. The spec also requires X; you didn’t handle it. Please update.”) Document the second cycle in prompts.txt and review.docx. Compare:

• Did the second response fix what you asked?
• Did it break anything that worked in the first response?
• Did you trust it more or less than the first?

This is a preview of the iterative refinement discipline of Chapter 13.

Hard Tier (+up to 25% additional extra credit)

The Hard tier asks you to deliberately make the AI worse, and document what happens. This is the harder skill: not just using AI well, but knowing exactly how it degrades when you use it badly.

H1. Bad spec, same class

Take the same class you implemented for Normal. Now write a deliberately bad spec — vague, ambiguous, missing edge cases, no examples. Something a careless engineer might write.

Send the bad spec to your AI with the same kind of prompt you used for the good spec. Save the new output. Then in review.docx, add a section titled “Bad Spec, Bad Output” comparing:

• What the AI produced from the good spec vs the bad spec.
• Which specific aspects of the output degraded.
• Whether the AI ever asked you for clarification (it usually doesn’t; that’s the point).
• One paragraph: “What is the cheapest spec-improvement that would have produced the biggest output-improvement?”

This rep teaches a thing no chapter can teach: the causal link between your spec quality and the AI’s output quality. After this rep, you will never again write a vague prompt without feeling it.

H2. Stand the code up against a real malicious tester

Hand your code (without your test suite) to a classmate. Ask them to write three tests designed specifically to break it. Run their tests against your code. Document what broke, what didn’t, and what you would have caught earlier if you’d written the malicious tests yourself.

This rep — defense by adversary — is how real code-review-driven teams catch the bugs that solo testers miss.

Submission

Submit one URL via the course portal:

• OnlineGDB project link — recommended. Put all five files (spec.txt, EventLog.java, EventLogTest.java, review.docx, prompts.txt) in the same project. If OnlineGDB’s UI only shows one file at a time, paste all markdown into a top comment block in EventLog.java and link from the project description.
• GitHub repo link — preferred if you have it set up. One repo per project. Push all five files to the root.

What EventLog.java must contain at the top

/*
 * Project 9 — Spec → AI → Review
 *
 * Tier targeted:    Normal / Medium / Hard
 * Class implemented: EventLog (or other)
 *
 * Files in this submission:
 *   - spec.txt           — my written specification
 *   - EventLog.java     — this file, AI-generated + my revisions
 *   - EventLogTest.java — my JUnit tests
 *   - review.docx         — my review of the AI's first output
 *   - prompts.txt        — every prompt I sent, with timestamps
 *
 * AI assistant used:    [Claude / GPT / Gemini / other], [model version if known]
 *
 * AI usage summary (one paragraph, honest):
 *   I wrote spec.txt by hand. I prompted [AI] for the implementation
 *   in one cycle. The first response was [X]% of the final code by
 *   line count. I made [N] specific changes, documented in review.docx.
 *   All tests were written by hand. I prompted the AI for [other thing,
 *   if any] and discarded the response because [reason].
 *
 * What I'd change if I had another hour:
 *   [one sentence]
 */

What the grader will do

1. Open prompts.txt first and read it end to end.
2. Open spec.txt and read your contract.
3. Open EventLog.java and read your code.
4. Run EventLogTest.java and confirm it passes.
5. Open review.docx and confirm your review aligns with what they see in the code and the prompts log.
6. Score against the rubric.

If any of those five steps reveals an inconsistency — your prompts log says you asked for X but your code shows Y — the grader will mark process points down. Honest logs above clever ones. Always.

Hints (Read These If You’re Stuck)

• “How long should the spec be?” For Normal, about a page. For a 3–6 method class, that’s roughly: one sentence purpose, one short paragraph per method (signature + behavior + errors), three example inputs/outputs, two invariants. Not a novel. Long enough to remove ambiguity.

• “My AI’s first answer looks perfect. Did I do it wrong?” Sometimes the AI just nails it on a simple class. That’s fine. But “looks perfect” is exactly the moment to read more carefully. Specifically check: did it expose internal collections (return list instead of return List.copyOf(list))? Did it handle null inputs? Did it handle empty inputs? If after a careful read it’s genuinely clean, write that in review.docx — and then write tests that prove it.

• “My AI keeps suggesting features I didn’t ask for.” Your prompt isn’t constraining enough. Re-prompt with explicit “do not add features not in the spec.” Log the original and the re-prompt both.

• “My AI’s code uses some library I’ve never heard of.” Suspect it. Try to compile. Look up the import in the Java 17 docs. If it’s hallucinated, that’s your hallucinated-API case for Medium-tier M1.

• “How long should this project take?” Normal: 2–4 hours including the prompts log. Medium: 4–6 hours. Hard: 6–10 hours. The Hard tier’s “bad spec” exercise is shorter than it sounds but the analysis takes real time.

What Mastery Looks Like (Beyond the Rubric)

The rubric tells you what to do. Here’s what to aim for:

A great Project 9 has a spec.txt that another student in the class could implement without ever talking to you. That’s the test of a good spec. If a reviewer has to message you to ask “what should this return on empty input?” — your spec was incomplete.

A great Project 9 has a review.docx where you can defend every change. “I changed return list to return List.copyOf(list) because the spec says callers cannot mutate internal state; the original code exposed it.” Specific. Reasoned. Not “I cleaned it up.”

A great Project 9 has a prompts.txt that reads like a transcript of senior engineering. Each prompt has a purpose. Each response has a noted reaction. No “just messing around” prompts hidden away. The grader should be able to reconstruct your hour from your log.

A great Project 9 has tests that would have failed on the AI’s first version and do pass on your final version. That delta — what the tests caught — is the single most valuable artifact in the project.

You can ship this in two hours if you’ve done the reps. You can ship a great version in four. Both are fine. Decide what you’re going for and commit.

When You’re Done

1. Read your prompts.txt from top to bottom out loud. Slowly. Does it tell an honest story?
2. Run all your tests. Do they pass? If they don’t, your project isn’t done.
3. Re-read your EventLog.java with the spec in your other hand. Does every method’s behavior match the spec exactly?
4. Sign your accountability sentence from Rep 11 at the bottom of review.docx.
5. Submit.
6. Read Chapter 10. Now we get serious about what the prompt is.

Coach’s Note — This is the project that decides whether Phase 2 lands for you. If you treat it as “easy because the AI does the work,” your Phase 2 grade will reflect it. If you treat it as “this is the workflow I’m building for the next 7 weeks and the next 4 years of my career,” your Phase 2 grade will also reflect it. Make it the second one. The students who ship a real Project 9 cruise into Project 10. The students who phone it in pay for it twice — first in Project 10, again in the final.

Welcome to the senior chair. See you Monday.