docs(openspec): plan hackathon-analysis change

[TOMOKI977]

Summary

Planning artifacts for change 3, hackathon-analysis. No code.

A team can analyze a hackathon page from the group's general chat, and later pin that analysis in the hackathon's forum topic:

• Commands:
  • /hackathon <url> (admin-only) queues a new analysis.
  • /hackathon <slug> re-shows an analysis. When an admin runs it inside a topic, it also links and pins the analysis there.
  • /hackathons lists the team's analyses.
• Free tier only:
  • Extraction uses Workers AI, with GLM-5.3-Flash as the primary model and DeepSeek V4 Flash as the fallback. Model IDs live in vars.
  • A plain fetch runs first. Browser Rendering is used only when the text is too thin.
  • Each team has a cap of 5 new analyses per day.
• Async: the webhook does the fast checks and replies "Analyzing …". A Cloudflare Queues consumer (max_concurrency: 1) runs the analysis and posts or pins the result. Jobs are tracked by id so a redelivered message is not processed twice.
• Safety:
  • SSRF guards apply to both the plain fetch and the browser path.
  • Page text is treated as untrusted.
  • Every field is nullable and must quote a snippet that appears on the page.
  • The raw page is never stored or logged.
• Suggestions: only repos already linked with /linkrepo.
• Deferred: date reminders, a manual project registry, multiple analyses per topic, and paid models.

Size exception: about 980 lines, all documentation.

Files

• openspec/changes/hackathon-analysis/explore.md, proposal.md, design.md, tasks.md
• openspec/changes/hackathon-analysis/specs/{hackathon-analysis,page-fetch,llm-extraction}/spec.md

Delivery plan

Ten PRs to main, in this order:

1. domain modules
2. ports and the analyze use case
3. queue request and job run
4. show, link and list
5. D1
6. static fetcher
7. browser fetcher
8. Workers AI and GitHub metadata
9. queue consumer
10. commands and config

The operator steps are tracked in tasks.md Phase 11: create the queue, enable the AI and Browser bindings, give the bot pin rights, and verify the model IDs.

🤖 Generated with Claude Code