Skip to content

Instantly share code, notes, and snippets.

@decagondev
Created June 24, 2026 18:13
Show Gist options
  • Select an option

  • Save decagondev/1bc018916e13fd9d80f3bfa8c2209048 to your computer and use it in GitHub Desktop.

Select an option

Save decagondev/1bc018916e13fd9d80f3bfa8c2209048 to your computer and use it in GitHub Desktop.

Hackathon Design Document — "The AI Wrote This"

Fuses: CC1 (Trust-but-Verify) × CC4 (Performance & Data-Shape) × CC5 (System Evolution) Companion doc: cross-cutting-hackathons.md §10.2 (and the §10 note on the 32K verification twist) Recommended slot: second flagship — run after the 32K rubric/harness is comfortable.

Attribute Value
Codename The AI Wrote This
Format Brownfield break-fix + 32K-style design defense
Duration 1–2 days (1 day lean, 2 days with the verification-twist variant)
Team size 1–3 (smaller than the others — this rewards individual judgment)
Difficulty ●●●●○
Native platform 32K rubric & build harness (defense half) + an AI-generated brownfield repo
Pass bar Total ≥ 70 and the corrected spec is buildable from the transcript alone

1. Premise

You've inherited a repository an LLM generated in one shot. It compiles, it looks professional, and it is quietly wrong: subtly buggy on an edge case, wrapped in abstraction nobody needed, and slower than it has any right to be. Your job is the modern engineer's actual job — not to write the code, but to judge it. Catch what the model got wrong, cut what it over-built, make it fast, and then explain your reasoning so clearly that a small free model could rebuild it correctly from your words alone.

This is the verification stance from CC1, applied with the performance discipline of CC4 and the decision-trail discipline of CC5.


2. Treasury topic coverage

Treasury topic Original category Cross-cut
Review AI-generated parser/validator + benchmark + rewrite + tests Benchmarking CC1 / CC4
AI-use ethics: produce wrong code, find the error, document detection Reading Code CC1
Use AI to learn while independently verifying correctness Reading Code CC1
Review AI architecture for unnecessary complexity Mixed CC1
AI prompt/context packet or spec-cleanup output Other CC1
10-minute spec-normalization defense Other CC1
Complexity / indexing / caching / serialization / data-shape tradeoffs Caching CC4
Data structures, algorithms & complexity Databases CC4
Load / stress tests Benchmarking CC4
Write ADRs; lead design review with challenge System Design CC5
Deeper TS/Python service design Lang-specific CC5
Architecture via case studies / failure reports / open-source internals Reading Code CC5

3. Learning objectives

  1. Detect a plausible-but-wrong correctness bug in generated code and document how it was detected.
  2. Recognise and remove needless abstraction — name what the indirection cost and why it wasn't earned.
  3. Diagnose and fix a performance problem rooted in data shape, not micro-optimization.
  4. Benchmark honestly — warm-up, noise, the right metric — and present a defensible before/after.
  5. Record decisions as ADRs and survive an adversarial design review.
  6. Explain reasoning to the 32K bar — clear enough that a small model rebuilds it correctly.

4. What participants are handed

An AI-generated repo — visibly so — built around one focused domain task (a parser, a validator, a small service). Planted into it, by design:

  • One subtle correctness bug. Passes the naive tests; fails a specific edge case (off-by-one on an empty input, a boundary the model didn't consider, a silent type coercion).
  • One or two needless abstraction layers. A factory-of-factories, a premature generic interface with a single implementation, an event bus where a function call would do.
  • One performance problem of data shape. O(n²) where O(n) fits, the wrong container for the access pattern, or serialization inside a hot loop.
  • A fixed benchmark harness so before/after numbers are comparable across participants.

Provide: the repo, the original (messy) prompt/spec the "model was given," and the 32K rubric.


5. Run of show

Lean (1 day)

Time Phase What happens
0:00–0:30 Briefing Premise, the 32K bar, rubric.
0:30–2:30 Track A — Verify (CC1) Find the correctness bug; remove the needless abstraction; write the detection note.
2:30–4:00 Track B — Perform (CC4) Diagnose the slowness; fix the data shape; produce honest before/after benchmark.
4:00–5:30 Track C — Defend (CC5) Write the ADRs; record the design-defense video.
5:30–6:30 Build & score Feed each defense transcript to the small model; run the build in the harness; grade.

With the verification-twist variant (2 days)

Day 1 = Tracks A–C above. Day 2 adds the twist (this is the §10 note made real): the small model's first build of the participant's corrected spec is deliberately wrong. The participant must catch that error and refine their explanation until the second build passes. It turns the whole event into a recursive verification exercise — they verify the AI, then verify the AI verifying them.


6. Deliverables

  1. The corrected code — bug fixed, abstraction removed.
  2. A detection note — for each defect: the signal that exposed it and how you confirmed it.
  3. A before/after benchmark with stated methodology (warm-up, runs, metric, environment).
  4. An ADR set justifying each change.
  5. A design-defense video + written design to the 32K bar.
  6. (2-day variant) A refined spec that survives the model's deliberately-wrong first build.

7. Scoring rubric (100 points)

Borrowed from the 32K ethos: reward arithmetic, named structures, explored dead-ends and honest measurement; penalise hand-waving.

Dimension Points What earns full marks
Correctness bug caught + detection documented 20 Bug found; the note shows a method, not luck.
Needless abstraction removed + justified 15 Indirection gone; the cost it imposed is named.
Performance fix correct 15 Right root cause (data shape), not a band-aid.
Benchmark honesty 15 Warm-up, noise and metric handled; no cherry-picking.
ADRs clear & defensible 15 Each decision traceable; survives the adversarial reviewer.
Design defense buildable by the model 20 Transcript alone rebuilds the corrected solution.

Pass = total ≥ 70 AND the corrected solution is buildable from the transcript (the 32K gate). In the 2-day variant, "buildable" means buildable on the model's second attempt after the participant catches the planted first-build error.


8. Defect bank (rotate per cohort)

Defect type Example planting The "tell" a sharp reviewer catches
Edge-case correctness empty-input or single-element path mishandled property test / boundary case fails
Silent coercion string/number mixing that "works" on sample data type audit at the boundary
Needless abstraction generic interface, one impl, three indirections "delete it and nothing breaks" test
Data-shape perf list where a set/map is needed; nested scan complexity read of the hot path
Serialization in hot loop JSON encode/decode per iteration profile shows the encoder dominating

Plant exactly one of each top category per repo so scoring maps cleanly to rubric rows.


9. Facilitator build checklist

  • AI-generated repo with one bug, one needless abstraction, one perf problem (from the bank).
  • The original messy prompt/spec, included as an in-world artifact.
  • Fixed benchmark harness (same machine profile / constraint box) so numbers compare.
  • 32K build harness + rubric wired in for the defense grading.
  • (2-day) A pre-authored "deliberately wrong first build" path for the twist.
  • Reference solution for graders (the intended fixes), kept private.

10. Hint laddering & safety nets

  • No bug found by mid-Track-A: reveal the category of defect (correctness / abstraction / perf), never the location.
  • Benchmark looks suspicious: prompt the team to state warm-up and run count rather than correcting them — honesty is the skill being graded.
  • Defense too vague to build: that's a fail condition, not a bug — but offer one re-record window if time allows.

11. Run-time risks & mitigations

Risk Mitigation
Drifts into "AI is bad" Frame as "AI + disciplined human"; the prompt/spec artifact shows AI did the grunt work fine.
Trivial defects ("spot the typo") Defects must be plausible; pilot the repo on a strong engineer first.
Hardware variance skews benchmarks Fixed harness / constraint box removes it.
Defense grading feels subjective The 32K "buildable from transcript" gate makes it objective: it builds or it doesn't.

12. Variants & stretch

  • Spec-normalization opener: start with the raw, messy spec and make participants clean it before any code — directly exercising the 10-minute spec-normalization defense (Treasury "Other").
  • Team relay: one person finds defects, another fixes perf, a third defends — forces handover clarity.
  • Open-source case study warm-up: assign a real failure report (CC5) the day before to calibrate judgment.

13. Day-of pre-flight checklist

  • Repo defects verified present and subtle (piloted).
  • Benchmark harness deterministic; baseline number recorded.
  • 32K build/grade harness green.
  • Rubric + ADR template + detection-note template shared.
  • (2-day) twist build path tested end-to-end.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment