Skip to content

docs: sync README with research-assist tool, judge calibration, and 8-title status - #8

Merged
serpeigd merged 2 commits into
mainfrom
claude/youthful-cray-vwudox
Aug 7, 2026
Merged

docs: sync README with research-assist tool, judge calibration, and 8-title status#8
serpeigd merged 2 commits into
mainfrom
claude/youthful-cray-vwudox

Conversation

@serpeigd

@serpeigd serpeigd commented Aug 7, 2026

Copy link
Copy Markdown
Owner

What changed

Documentation-sync pass on the README (and two small doc/docstring fixes elsewhere). No code behavior changed; pytest tests/ still 8/8 green.

  • Live demo link was missing entirely — added https://twistify.onrender.com with the already-documented Render free-tier cold-start/filesystem-reset caveat (couldn't independently verify reachability from this sandbox — outbound egress to that host is blocked by the sandbox's network proxy; treat as expected Render free-tier behavior per CLAUDE.md, not a broken link).
  • Fixed a stale "7 hand-researched" count → 8. Gone Girl was added to content/researched/ (git log confirms, and the folder has 8 files) before this sync started, but the README, and docs/DESIGN.md's "Pending" section, and webapp/resolve_tmdb_ids.py's docstring, still said 7. Fixed all three. (CLAUDE.md itself has the same stale "7 hand-researched films" line in its "What this is" section — left untouched since it wasn't in scope, flagged for the repo owner instead.)
  • Documented webapp/research_assist.py (D14) for the first time in the README: what it does (Wikipedia+TMDB retrieval → drafted ContentPack), the best-of-3 generation design, the sanitize_grounding() code-level safety net, and its honest current status (tested end-to-end on one title, Citizen Kane).
  • New sections: Configuration (.env keys — TMDB/GROQ/ANTHROPIC/UPSTASH, all optional, nothing paid required), Project layout, Roadmap (mirrors CLAUDE.md's "Next task"), Limitations (states the SubstringJudge/LLMJudge recall gap plainly up top instead of leaving it implicit further down the page).
  • Badges: added Groq and TMDB — both genuinely load-bearing (free baseline generator, LLMJudge calibration, research-assist, browse-tier posters) and previously undocumented.

Verified before writing

  • git log --oneline -30, full repo tree, docs/DESIGN.md D1–D14.
  • pytest tests/ -v → 8/8 pass.
  • Ran python webapp/app.py locally, confirmed it serves and the two existing screenshots still match the UI mechanics shown (spoiler curtain, catalogue sidebar) — the sidebar's "Con contenido" badge count in the screenshots is stale at 7 vs. the real 8 now, a cosmetic one-off discrepancy not worth a screenshot regen per the task's "don't fabricate screenshots of features that don't visually differ" guidance; flagging it here instead.
  • Every CLI command referenced in the README against the actual argparse/docstrings in evals/run_eval.py, webapp/prewarm_translations.py, webapp/resolve_tmdb_ids.py, evals/calibrate_*_external.py.
  • .gitignore to confirm content/_drafts/ (research-assist output) and .env are correctly excluded, matching what the README now claims.

Left for the repo owner

  • The LLMJudge/SubstringJudge recall gap (0.089 / 0.0) is a genuine, unresolved limitation — now stated plainly in a dedicated Limitations section rather than only inside the results tables. Per CLAUDE.md's "Next task", Milestone 1 (retrieval) shouldn't start until this is resolved.
  • CLAUDE.md's own "What this is" section still says "7 hand-researched films" (its "Status" section elsewhere correctly says 8/20) — a small internal inconsistency, not touched since CLAUDE.md wasn't in this task's scope.
  • Screenshot refresh (7→8 "Con contenido" badge) is optional/cosmetic, not blocking.

Generated by Claude Code

claude added 2 commits August 7, 2026 06:47
…-title status

- Add the live demo link (was missing entirely) with the documented
  Render free-tier cold-start/filesystem-reset caveat.
- Fix stale '7 hand-researched' counts to 8 (Gone Girl was added to
  content/researched/ before this sync) across README and DESIGN.md's
  Pending section; same fix in resolve_tmdb_ids.py's docstring.
- Document webapp/research_assist.py (D14): what it does, the best-of-3
  design, the sanitize_grounding() safety net, and its current
  one-title-tested status -- new README section plus a Status/How-it's-
  built/Roadmap mention.
- Add Configuration (.env keys: TMDB_READ_ACCESS_TOKEN, GROQ_API_KEY,
  ANTHROPIC_API_KEY, UPSTASH_REDIS_REST_URL/TOKEN -- all optional,
  nothing paid required), Project layout, Roadmap (from CLAUDE.md's
  Next task), and Limitations sections.
- Limitations states the SubstringJudge/LLMJudge recall gap plainly
  (recall 0.0 / 0.089) instead of leaving it implicit in the results
  tables further down.
- Add Groq and TMDB badges -- both genuinely load-bearing (free baseline
  generator, LLMJudge calibration, research-assist, browse-tier posters)
  and previously undocumented in the badge row.

Verified before writing: git log, docs/DESIGN.md D1-D14, all CLI
commands in evals/run_eval.py's argparse, content/researched/ file
count, pytest (8/8 pass), and a local run of webapp/app.py.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VCyfwtJ1wiBGdiiscqufRU
@serpeigd
serpeigd marked this pull request as ready for review August 7, 2026 07:01
@serpeigd
serpeigd merged commit 743892e into main Aug 7, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants