samber/dev-event-organizer-skills已通过检查
SKILL DETAIL
hackathon-brief-design
samber/dev-event-organizer-skills/hackathon-brief-design
Write the hackathon challenge document teams read before they build - problem statements sized to the time box, thematic challenge tracks, the published rules and eligibility text, the submission-artifact checklist, sponsor-challenge framing, and naming (never weighting) the evaluation categories. Use whenever the user mentions a hackathon brief, challenge or track prompts, hackathon rules or eligibility, submission guidelines, or turning a sponsor's API into a challenge - even if they never say "brief". Challenge tracks here are thematic categories a team enters, not parallel session streams. Do NOT use for rubric weights and judging mechanics - use samber/dev-event-organizer-skills@hackathon-judging instead.
安装量 · 235查看来源
Installation
npx skills add https://github.com/samber/dev-event-organizer-skills --skill hackathon-brief-design
技能文件
SKILL.md
最近同步 · 2026年10月18日
evals/evals.json›
{
"skill_name": "hackathon-brief-design",
"evals": [
{
"id": 1,
"prompt": "I'm writing the participant document for NordByte Hack, 36 hours, in-person in Malmö, about 90 hackers expected. Can you write me the judging-criteria section? We have 3,000 EUR for first place and 1,000 EUR for second, and I want teams to know exactly how we score so nobody complains afterwards. Four criteria feels about right. Give me the finished text I can paste in.",
"expected_output": "A categories section that names the evaluation categories with a written description each, prints the elimination criteria alongside them, publishes an exclusion list of what is not judged, and carries no weights, no scale, no point totals and no prize figures - with the weighting and the amounts explicitly routed elsewhere.",
"files": [],
"expectations": [
"Names the evaluation categories without attaching any percentage, weight, point value or score total to any of them",
"States no scoring scale (no 1-5, no 1-10, no 'out of 100') anywhere in the brief text produced",
"States explicitly in the brief who weights the categories and when the weights will be published",
"Routes criteria weights and the scoring scale to samber/dev-event-organizer-skills@hackathon-judging",
"Gives each named category a written description of what a judge is looking for, not a bare label",
"Notes that the technology/design/completion/learning set fits a learning-oriented event and must be adapted rather than copied",
"Prints the elimination criteria next to the category names rather than inside a weighted rubric",
"Publishes an exclusion list naming what is not judged, each exclusion carrying its reason",
"Explains that teams optimize for whatever the brief names, as the reason the exclusion list exists",
"Omits the 3,000 EUR and 1,000 EUR figures from the brief text, referring to a prize per place or per track instead",
"Routes prize amounts and cash-versus-in-kind to samber/dev-event-organizer-skills@hackathon-cash-prize",
"Avoids 'bonus points' phrasing or any other wording that leaks a weighting decision"
]
},
{
"id": 2,
"prompt": "Our format lead already locked the judging structure for Copperline Hack: expo tables, six judges walking the room for two hours on Sunday morning. Now I need the submission guidelines written. My plan was to require every team to upload a 2-minute demo video plus a slide deck, and submissions close 'when hacking ends'. 120 hackers, in person, Berlin. Write the section.",
"expected_output": "A submission checklist derived from the expo-table structure: live demo carries the judging, video not required, code link plus readme plus written description plus key hygiene plus AI-tool disclosure, and a deadline stated as wall-clock time in a named time zone with a late policy and a definition of what counts as submitted.",
"files": [],
"expectations": [
"Flags requiring a demo video at an expo-table event as a mistake and removes it from the mandatory list",
"States that if a video is kept at all it is explicitly labelled optional in the brief",
"Requires the team to be present at its table for the whole judging window",
"Does not require a separately judged slide deck for an expo-table event",
"Requires a publicly available code link, ideally a git repository",
"States that the code must remain public after the event to stay prize-eligible",
"Requires API keys to be removed before the link is shared",
"Requires libraries and frameworks used to be listed in a readme",
"Requires AI-tool use to be disclosed in the submission, written as a disclosure requirement rather than a usage ban",
"Requires a one-paragraph written description of what the project does and who it is for",
"Replaces 'when hacking ends' with a wall-clock deadline time in a named time zone",
"Places the deadline before the first judging slot rather than at it",
"States the late policy in the brief before anyone is late",
"States what counts as submitted, including that an unreachable or private link is not a submission",
"Treats the expo-table structure as a fixed input and does not re-decide the demo format"
]
},
{
"id": 3,
"prompt": "Kestrel Labs Devfest planning. 400 hackers have registered. On the Friday we're running 3 parallel session tracks, so for Saturday's hackathon I was going to do 8 challenge tracks - that's roughly 50 people per track which feels healthy, and it spreads the submissions out so each track has a real contest. Two sponsors are funding prizes. We have 6 judges confirmed. Does 8 work?",
"expected_output": "A correction of both the headcount-scaled track count and the field-splitting assumption, a track count argued from judging and sponsor capacity, a clear separation of challenge tracks from parallel session streams, and the cross-track submission rule published in the brief.",
"files": [],
"expectations": [
"Rejects scaling the challenge-track count to participant headcount",
"States that no published ratio links track count to participant headcount",
"Scales the track count to judging capacity, naming what the judges running deliberations can absorb",
"Treats sponsor and judge headcount, not participant headcount, as the variable the ceiling tracks",
"Cites the guidance to aim for about 3 tracks absent sponsor tracks and without an overall first/second/third placement",
"States that a track count of 20 or more is beyond any recommended ceiling",
"Corrects the '50 people per track' assumption by stating a team submits one project that may enter several challenge tracks",
"States that adding a challenge track does not split the field or reduce submission density per track",
"Requires publishing both halves of the cross-track rule: teams may not submit multiple projects, and may submit to multiple challenges",
"Distinguishes a challenge track (a thematic category a project is entered into) from a parallel session stream",
"Does not carry the 3 Friday session tracks into the challenge-track count",
"Names the marginal cost of an extra track as rules-consistency work rather than lost submissions",
"Recommends a general track plus sponsor tracks structure given the two funded prizes"
]
},
{
"id": 4,
"prompt": "Meridian Cloud is funding our entire prize pool for Forgeworks Hack and they want the event branded 'Built on Meridian' - every team has to use their API, no exceptions. Their partner manager told me on a call the docs are great and the rate limits are fine for a few hundred users. Nobody on our team has actually used it. 200 hackers, 48 hours, in person. Write the sponsor track wording for the brief.",
"expected_output": "A refusal to publish a sole-substrate requirement without written confirmations, a fallback to the optional bonus challenge pending those confirmations, a constraint written as a capability rather than a brand instruction, a published access path, and a published fallback sentence for an unavailable integration.",
"files": [],
"expectations": [
"Refuses to make the sponsor's API the event's sole substrate without written confirmation of a sandbox or offline fallback",
"Requires written confirmation of rate-limit headroom for the expected team count before any required use",
"States that the partner manager's verbal assurance is not sufficient and that the sponsor's own claim about its docs is not evidence",
"States that nobody on the organizing team having built something small end to end against the API blocks even the required-for-one-track rung",
"Recommends the optional bonus challenge as the rung to publish pending those confirmations",
"Writes a published fallback sentence stating that a team whose sponsor integration is unavailable through no fault of its own is judged on its design and integration plan rather than a working call",
"States that the fallback must be written before the event, because improvised during an outage it is a favour rather than a rule",
"Writes the track constraint as a capability the submission must demonstrate rather than as 'must use Meridian'",
"Publishes the access path in the prompt itself: where keys come from, the rate limit, and who to contact when it fails",
"Requires rewriting the sponsor's marketing copy into a problem and having the sponsor confirm the rewrite",
"States in the sponsor prompt that entering the sponsor track does not forfeit the general prize",
"Treats dependency risk as a separate finding from effort, and states that promotion never overrides the delete"
]
},
{
"id": 5,
"prompt": "Halden Hack, 48 hours, in-person in Oslo, open to anyone 18 and over, not a student event. We're forking MLH's published rules rather than writing our own. One thing: our biggest sponsor's legal team asked us to add an IP section saying teams grant the sponsor a perpetual non-exclusive licence to any code submitted to their challenge track. Paste me the final rules and eligibility text ready to publish.",
"expected_output": "An adopted rule set with every event-specific field listed and edited, no IP clause written, and the sponsor's licence request routed to counsel through the sponsor-agreement skill rather than drafted into the brief.",
"files": [],
"expectations": [
"Writes no intellectual-property or licence clause and recommends none",
"States that the adopted rule set carries no IP-ownership term, no ownership assignment and no originality warranty",
"Routes the sponsor's licence request to counsel via samber/dev-event-organizer-skills@event-sponsor-agreement",
"States that who owns submitted work is a jurisdictional legal question, not something a brief template settles",
"Treats 'participants keep their work' as an assumption to confirm rather than a fact to publish",
"Lists the event-specific fields that must be edited before publishing rather than adopting the set unchanged",
"Names hacking start and end times as a field the adopted set ships without",
"Replaces the 'This event is limited to students' line rather than deleting it, since the event is open to anyone 18 and over",
"Replaces the judging-mode line with the structure actually chosen for this event",
"Requires a crossposting decision to be stated either way",
"Points the code-of-conduct link at the organizer's own document and the disqualification-reporting channel at a person or address the organizer controls",
"Treats the team-size number as a fixed input from samber/dev-event-organizer-skills@hackathon-team-formation and publishes it with the solo-entry answer",
"Defines every eligibility word that could be argued and uses a numeric boundary where one exists"
]
},
{
"id": 6,
"prompt": "Vantage Retail is running a 30-hour internal hack for about 60 engineers. All I have is the theme, 'smarter stores', and my co-organizer thinks we should build starter repos with acceptance tests for each prompt so judging is objective and fair. How specific should the prompts be, and can you draft one so I can see the shape?",
"expected_output": "A structured statement recommended as the rung for a 30-hour box, the fully specified rung declined with its promotion condition named, and a drafted prompt carrying all five parts including a stated minimum viable submission.",
"files": [],
"expectations": [
"Recommends the structured statement as the default rung for this time box",
"Declines the fully specified rung with starter repo and acceptance tests for a 30-hour event",
"States the promotion condition for fully specified: a time box of a week or longer, or a sponsor whose own integration tests already exist and can be handed over as-is",
"States that below roughly a weekend the fully specified rung changes what the event is, turning a build into a graded exercise",
"Names all five parts of the structured statement: context, the challenge as a question, constraints, resources provided, and a minimum viable submission",
"Phrases the drafted challenge as a question ending in a question mark",
"Keeps the drafted constraints to things a judge could actually check",
"Names what is not provided alongside what is, in the resources part",
"States a minimum viable submission in the drafted prompt, naming the smallest thing that counts as a real entry",
"Cites the 25% observation as 25% of a team's own pre-hack estimate of its own scope",
"States that the 25% figure is not a completion rate and not a ratio against the organizer's prompt",
"Labels the 25% figure as one practitioner's observation rather than a measured rate",
"Applies the twenty-minute onboarding test if any starter environment is provided"
]
},
{
"id": 7,
"prompt": "Loop Hack is adding a beginners track this year. Around 120 people signed up and maybe a third say it's their first hackathon. My plan was to look at each team when judging starts and decide whether they're beginner enough to count for that track - keeps it flexible and stops people gaming it. How should I word the track in the brief?",
"expected_output": "A refusal to adjudicate carve-out eligibility after teams have formed, and a four-part published carve-out stating who qualifies, what fraction of the team must qualify, how it is evidenced, and what happens when membership changes.",
"files": [],
"expectations": [
"Rejects deciding beginners-track eligibility at judging time, after teams have already formed",
"Requires the qualifying fraction of the team to be published before the event and before people choose teammates",
"States who qualifies as a beginner in words that could be argued only one way",
"States what fraction of the team must qualify",
"States how beginner status is evidenced at submission time",
"States what happens to a team that becomes ineligible when a member joins or leaves",
"Treats 'at least half the team' as one event's number rather than a standard to copy",
"States that the carve-out wording must compose with the base rules without contradicting them",
"Notes that the carve-out moves the rules rung from the adopted standard set to adopted plus carve-outs",
"States that the brief publishes before registration closes and then freezes"
]
},
{
"id": 8,
"prompt": "Realistic constraints for Saltmarsh Hack: the brief has to be live in 4 days, I personally have about 5 hours to spend on it, and we have no lawyer and no budget for one. Prize pool is 5,000 EUR from two sponsors. We expect a handful of 16-year-olds from the local technical school, and the submission form collects names, emails and school. First edition but we intend to run it every year. What do I do?",
"expected_output": "An adopted standard rule set promoted by the near publication date, the fully specified rung demoted, the no-counsel route to legal-grade text closed rather than substituted, and the minors and personal-data answers handled as obligations rather than menu choices.",
"files": [],
"expectations": [
"Promotes the adopted standard rule set over anything drafted, because the publication date is near",
"Demotes the fully specified problem-statement rung, naming its starter repo and acceptance tests as the longest lead time on offer",
"States that having no counsel removes the route to full legal-grade text rather than merely demoting it",
"Refuses to substitute self-written legal-sounding text and says so plainly rather than quietly drafting it",
"Treats 16-year-olds attending as an obligation requiring review before publication, not a rung to trade against effort",
"Treats personal data collected through the submission as a second obligation requiring the same pre-publication review",
"Names who performs that review: counsel, or whoever owns data protection for the organizing entity",
"Deletes the minimal rules rung because the prizes carry cash value and sponsors fund them",
"States that a recurring edition promotes the rungs written once and reused, because their cost amortises across editions",
"Keeps the 5,000 EUR figure out of the brief text and routes prize amounts to samber/dev-event-organizer-skills@hackathon-cash-prize",
"States that the code of conduct is linked at every rung and is never traded against effort"
]
},
{
"id": 9,
"prompt": "Tidewater Hack, here's where we landed, tell me if we're good to publish tonight. Hacking runs Saturday morning to Sunday morning. Eligibility: open to all. Teams: up to 5 people. Challenge tracks: AI, Climate, Open - each has a problem statement written. Submission: GitHub link and a readme. Evaluation categories: Technology, Design, Completion. Sponsors: two, each with a track. Registration closes Thursday. Ship it?",
"expected_output": "A refusal to approve publication, a structural pass-threshold check naming which of the seven required items are missing or blank, an ambiguity pass on the stated rules, and a section-by-section validation offer before an explicit approval gate.",
"files": [],
"expectations": [
"Refuses to approve publication as it stands",
"Runs a structural pass threshold of seven items that must exist in writing with zero blanks",
"States that the threshold is self-set rather than an industry standard",
"Flags that the hacking window is not stated as start and end wall-clock times",
"Flags that no minimum viable submission is stated for any track's problem statement",
"Flags that there is no submission deadline and no late policy",
"Flags that the submission checklist is not derived from the chosen demo format",
"Flags 'open to all' as an eligibility statement whose arguable words are undefined",
"Runs the ambiguity gate by naming, for a rule, the reading a team arguing the opposite would point at",
"States that iteration continues until all seven items exist",
"Attaches no weight, scale or total to Technology, Design and Completion",
"Recommends presenting the brief section by section for validation rather than as one block",
"Requires explicit approval before publishing, since publication is the point of no return"
]
},
{
"id": 10,
"prompt": "Civic Forge is our community hackathon - people bring their own projects and pitch them to each other on Friday night, then teams form around whatever gets traction. I want the brief to basically just say 'build something for your city' and otherwise stay out of the way. One local consultancy is putting up a prize for best use of open data. 24 hours, about 70 people. Write the challenge section.",
"expected_output": "The open theme deleted because a sponsor funds a prize, a stated criterion written for the sponsor's prize, and the pitch mechanic published with the problem-not-solution refinement, an evidence requirement and a stated minimum before building.",
"files": [],
"expectations": [
"Deletes the open theme rung because a sponsor funds a prize",
"States that a sponsor prize needs a published criterion to attach to, or it becomes an improvisation at the ceremony",
"Writes a stated criterion or named challenge track for the open-data prize rather than leaving it unattached",
"Keeps the pitch mechanic and states that publishing it, rather than publishing the problem, is the brief's job where participants bring their own problems",
"Requires the pitch to state a problem rather than a solution",
"Explains why: a team pitching a solution commits to an approach before anyone has tested whether the problem is real",
"Publishes an evidence requirement for the pitch, such as interviews, numbers or a lived account",
"Publishes a stated minimum a team must reach before it may move to building",
"Hands the pitch mechanic content to samber/dev-event-organizer-skills@hackathon-team-formation",
"Notes that leaving the in-scope question open generates clarification traffic the organizer answers during the event"
]
},
{
"id": 11,
"prompt": "Argonaut Health internal hackathon, 80 engineers, working on de-identified patient records from our own warehouse. Our draft brief copies the public-repo and public-video rules straight from the usual template. Separate problem: teams started building yesterday morning and we just realised the brief never says anything about reusing repos they already had. Can I send an email tonight adding that rule?",
"expected_output": "The public-code and public-video requirements rejected for a client-data event with a replacement visibility rule named, and the mid-event rule addition refused in favour of a clarification, with the pre-existing-work position explained as what should have been published.",
"files": [],
"expectations": [
"Rejects the public-code requirement for this event, stating it assumes a culture that is open by default",
"Requires stating what replaces the visibility rule, because 'submit your code' with no visibility rule produces a submission nobody can open",
"Rejects the public-video requirement for the same reason",
"Refuses to add a new rule after teams have started building",
"States that a rule added mid-event re-scores teams that already finished, or applies to a competition nobody entered",
"Offers a clarification of the existing text as the available move, distinct from a new rule",
"States the idea/code split: a team may reuse an old idea but not old code",
"States that teams may use libraries, frameworks and open-source code",
"States that open-sourcing a prior project for the sole purpose of reusing it during the event is not allowed",
"States that any post-deadline allowance must name where the line sits between small fixes and new features",
"Records the clarification question as a signal naming a sentence the next edition's brief needs"
]
},
{
"id": 12,
"prompt": "GreenGrid is a themed hackathon on grid resilience. 160 participants registered, and we've lined up 12 utility engineers who will each bring a real problem from their own work. My board wants a measurable target in the plan: a similar event last year published 8% invalid submissions and a 4% disqualification rate, so I said we'd aim to come in under both. Sanity-check the plan for me.",
"expected_output": "The borrowed rates refused as targets, the self-set structural gate used instead, and the expert-to-participant pairing ratio applied to the 160 participants with the shortfall against 12 experts named.",
"files": [],
"expectations": [
"Refuses to adopt another event's invalid-submission or disqualification rate as a target",
"States that those rates are not comparable across formats, sizes and audiences",
"States that no platform or academic survey publishes an aggregate disqualification or rule-dispute rate for the field",
"States that every gate used here is self-set rather than an industry standard, and says so when presenting it",
"Applies the ratio of one expert-plus-workable-project pairing per four non-expert participants",
"States that the ratio counts participants, not teams",
"States that the ratio counts expert-plus-project pairings, not challenge tracks",
"Computes the required number of pairings from the 160 participants and names the shortfall against the 12 experts lined up",
"Names the failure the ratio prevents: participants struggling to find something relevant to work on",
"Requires each expert's domain problem to be translated into a workable project rather than published as-is",
"Substitutes the structural pass threshold for a rate target as the thing to measure before publication",
"Names the signals to record for the next edition: clarification questions asked, submissions rejected as invalid and why, and tracks that drew no entries"
]
}
],
"trigger_queries": [
{ "query": "Write the challenge brief for our 36-hour AI hackathon with two sponsor tracks and a beginners track", "should_trigger": true },
{ "query": "What rules and eligibility text do we publish for our hackathon, and what should we not write ourselves?", "should_trigger": true },
{ "query": "Our sponsor wants their API used - how do we word that without breaking the event if it goes down?", "should_trigger": true },
{ "query": "Turn our expo-table judging into a submission checklist and a deadline", "should_trigger": true },
{ "query": "We have a theme but no problem statements. How specific should they be for one weekend?", "should_trigger": true },
{ "query": "help, hackathon opens in five days and we have literally nothing written for participants to read", "should_trigger": true },
{ "query": "Draft the eligibility section for our student hackathon", "should_trigger": true },
{ "query": "Can we just fork MLH's rules for our event?", "should_trigger": true },
{ "query": "How many challenge tracks should we run?", "should_trigger": true },
{ "query": "We want a beginners category - how do we word who qualifies for it?", "should_trigger": true },
{ "query": "What do teams actually have to hand in at the end of the weekend?", "should_trigger": true },
{ "query": "Should we require a demo video from every team?", "should_trigger": true },
{ "query": "Write the problem statement for our sustainability track", "should_trigger": true },
{ "query": "Our sponsor sent us their marketing copy and wants it used as the challenge, help", "should_trigger": true },
{ "query": "What happens if a team can't get an API key during the event?", "should_trigger": true },
{ "query": "When does the submission deadline need to be, relative to judging?", "should_trigger": true },
{ "query": "What do we tell teams about using AI coding tools during the build?", "should_trigger": true },
{ "query": "Can teams reuse code from a side project they started last month?", "should_trigger": true },
{ "query": "Do we say that teams keep ownership of what they build?", "should_trigger": true },
{ "query": "We're not sure whether to let people enter the same project in two categories", "should_trigger": true },
{ "query": "List the evaluation criteria we should publish before the event", "should_trigger": true },
{ "query": "What should we tell teams we are NOT judging?", "should_trigger": true },
{ "query": "Someone asked if solo entries are allowed and I realised we never wrote it down anywhere", "should_trigger": true },
{ "query": "We want to publish a starter repo with acceptance tests - overkill for 24 hours?", "should_trigger": true },
{ "query": "How do I stop teams starting something they have no chance of finishing?", "should_trigger": true },
{ "query": "What goes in the document participants read before they start building?", "should_trigger": true },
{ "query": "Write the part that says who can enter and who can't", "should_trigger": true },
{ "query": "Our engineers are asking what counts as a valid entry, we never defined it", "should_trigger": true },
{ "query": "Put together the challenge document for HackNantes next month", "should_trigger": true },
{ "query": "The signed sponsorship deal promises them a named track - what exactly do I write?", "should_trigger": true },
{ "query": "Can I add a rule now? People started coding this morning", "should_trigger": true },
{ "query": "How do we phrase 'at least half the team must be first-timers' so it holds up?", "should_trigger": true },
{ "query": "What time zone should the deadline be stated in?", "should_trigger": true },
{ "query": "Our event is fully online this year - does that change what teams have to submit?", "should_trigger": true },
{ "query": "We're running a corporate hackathon on internal data, can we still require public repos?", "should_trigger": true },
{ "query": "How do we make sure teams know what 'done enough' means before they start?", "should_trigger": true },
{ "query": "Writing the participant-facing doc for our 48h build weekend", "should_trigger": true },
{ "query": "Three sponsors each want their own prize - how do I structure what teams enter?", "should_trigger": true },
{ "query": "Need the rules and eligibility text finished before registration opens tomorrow", "should_trigger": true },
{ "query": "Is 'build something with AI' enough of a prompt for a two-day event?", "should_trigger": true },
{ "query": "What exactly do we require in the readme?", "should_trigger": true },
{ "query": "Should the document say how many points each criterion is worth?", "should_trigger": true },
{ "query": "We want teams to pitch their own ideas on Friday night - what does the document cover then?", "should_trigger": true },
{ "query": "What should the submission form ask each team for?", "should_trigger": true },
{ "query": "How do I word a track so it reads as a problem and not as an advert for our sponsor?", "should_trigger": true },
{ "query": "We keep getting the same scope question from teams - what did we get wrong in writing?", "should_trigger": true },
{ "query": "Draft what happens to a team that submits late", "should_trigger": true },
{ "query": "Do participants have to be students, and how would we even define that?", "should_trigger": true },
{ "query": "Write the challenge prompts for our civic tech weekend", "should_trigger": true },
{ "query": "Give me the text that tells hackers what the categories are called", "should_trigger": true },
{ "query": "Is there a standard set of hackathon rules we can adopt instead of drafting our own?", "should_trigger": true },
{ "query": "Our judging is video-only this year, what do we require teams to upload?", "should_trigger": true },
{ "query": "We have minors attending - does that change the text we publish?", "should_trigger": true },
{ "query": "What's the minimum a team needs to show for it to count as a real entry?", "should_trigger": true },
{ "query": "The document is basically done - anything we've forgotten before we publish it?", "should_trigger": true },
{ "query": "A team is arguing our rule means the opposite - how do I write rules that don't do that?", "should_trigger": true },
{ "query": "How do I describe the dataset we're handing teams, and the one we're not?", "should_trigger": true },
{ "query": "Should crossposting to another hackathon be allowed, and where do we say it?", "should_trigger": true },
{ "query": "Writing up the challenge statement for our internal innovation day build sprint", "should_trigger": true },
{ "query": "A local company wants to fund an open-data prize - how does that become a track?", "should_trigger": true },
{ "query": "What do we publish about grounds for disqualification?", "should_trigger": true },
{ "query": "First hackathon we've ever run - what document do teams actually need from us?", "should_trigger": true },
{ "query": "The sponsor's API went down during our testing - what do we put in writing about that?", "should_trigger": true },
{ "query": "How long should the demo video be and what has to appear in it?", "should_trigger": true },
{ "query": "Set the weights for our hackathon rubric", "should_trigger": false },
{ "query": "How many judges do we need for 45 teams in a two-hour window?", "should_trigger": false },
{ "query": "Normalize scores between two judges who grade very differently", "should_trigger": false },
{ "query": "What's the tie-break if two projects end up on the same score?", "should_trigger": false },
{ "query": "A sponsor wants to judge its own track - is that a conflict of interest?", "should_trigger": false },
{ "query": "Brief our jury the morning judging starts", "should_trigger": false },
{ "query": "How do we announce results when a team formally contests the outcome?", "should_trigger": false },
{ "query": "What scale should judges score on, 1-5 or 1-10?", "should_trigger": false },
{ "query": "How big should our hackathon prize pool be?", "should_trigger": false },
{ "query": "Cash or cloud credits for the winners?", "should_trigger": false },
{ "query": "Split 10,000 EUR across three places and two sponsor tracks", "should_trigger": false },
{ "query": "Can a 16-year-old legally receive prize money at our event?", "should_trigger": false },
{ "query": "How do we actually pay out to a winning team based in another country?", "should_trigger": false },
{ "query": "Do we have to withhold tax on hackathon prizes?", "should_trigger": false },
{ "query": "Design the team-matching session for Friday night", "should_trigger": false },
{ "query": "What do we do with someone nobody picked for a team?", "should_trigger": false },
{ "query": "When should team membership freeze relative to the opening?", "should_trigger": false },
{ "query": "How many mentors do we need for 30 teams?", "should_trigger": false },
{ "query": "Where do we recruit hackathon mentors from?", "should_trigger": false },
{ "query": "Can a mentor write code directly in a team's repository?", "should_trigger": false },
{ "query": "Build the mentor shift rota across the overnight window", "should_trigger": false },
{ "query": "Single track or multi track for our conference sessions?", "should_trigger": false },
{ "query": "Should the hackathon be judged by expo table or by stage pitches?", "should_trigger": false },
{ "query": "Should we run this hybrid or in person only?", "should_trigger": false },
{ "query": "What mix of talks and workshops for a one-day event?", "should_trigger": false },
{ "query": "Write our call for papers", "should_trigger": false },
{ "query": "Should CFP review be blind or named?", "should_trigger": false },
{ "query": "Score the 200 talk submissions we received", "should_trigger": false },
{ "query": "Draft our code of conduct", "should_trigger": false },
{ "query": "Who responds to a code of conduct report during the event?", "should_trigger": false },
{ "query": "Negotiate the IP clause in our sponsorship contract", "should_trigger": false },
{ "query": "Build the sponsor prospectus tiers", "should_trigger": false },
{ "query": "How much should a gold sponsorship cost?", "should_trigger": false },
{ "query": "Write a cold outreach email to prospective sponsors", "should_trigger": false },
{ "query": "Make sure the sponsor actually gets everything they paid for", "should_trigger": false },
{ "query": "Run a demo day for startups at our conference", "should_trigger": false },
{ "query": "Brief the investor panel for our pitch competition", "should_trigger": false },
{ "query": "How long should each startup pitch be on stage?", "should_trigger": false },
{ "query": "Write the prerequisites for our Kubernetes workshop", "should_trigger": false },
{ "query": "How many helpers per workshop room?", "should_trigger": false },
{ "query": "The venue wifi can't handle 200 laptops at once", "should_trigger": false },
{ "query": "Find a venue for 300 people in Lyon", "should_trigger": false },
{ "query": "Build the event budget spreadsheet", "should_trigger": false },
{ "query": "Write the run of show for Saturday", "should_trigger": false },
{ "query": "Recruit and schedule our volunteers", "should_trigger": false },
{ "query": "Write the copy for our event landing page", "should_trigger": false },
{ "query": "What should early bird tickets cost?", "should_trigger": false },
{ "query": "What's our plan if a keynote speaker cancels the night before?", "should_trigger": false },
{ "query": "Lay out the session grid so the popular talks don't clash", "should_trigger": false },
{ "query": "Work back a planning timeline from the event date", "should_trigger": false },
{ "query": "Design the post-event attendee survey", "should_trigger": false },
{ "query": "Run the organizer debrief now that the event is over", "should_trigger": false },
{ "query": "Make the event accessible for wheelchair users", "should_trigger": false },
{ "query": "Plan catering and dietary requirements for the weekend", "should_trigger": false },
{ "query": "How do we get a company to sponsor our hackathon in the first place?", "should_trigger": false },
{ "query": "Write a product requirements document for our new feature", "should_trigger": false },
{ "query": "Write a creative brief for our agency", "should_trigger": false },
{ "query": "Draft an RFP for a video production vendor", "should_trigger": false },
{ "query": "Write a design brief for the event logo", "should_trigger": false },
{ "query": "Write a marketing campaign brief for the product launch", "should_trigger": false },
{ "query": "Brief our press contacts ahead of the announcement", "should_trigger": false },
{ "query": "Write a project brief for the engineering team", "should_trigger": false },
{ "query": "How do we decide whether to run a hackathon at all this year?", "should_trigger": false },
{ "query": "Design the workshop day that runs before the hackathon", "should_trigger": false }
]
}
references/problem-statement-patterns.md›
# Problem statements: the four rungs, the skeleton, and sizing to the time box
Contents: the four rungs in detail · the structured-statement skeleton · a worked pair (weak and rewritten) · a real published example · sizing ambition to the time box · themed-event capacity planning · wording a sponsor prompt differently from a general one.
## The four rungs in detail
**Open theme.** One phrase - "build something with AI", "civic data". Correct only where participants arrive with their own problems and pitch them to each other; the brief's job then is to publish the pitch mechanic and the rules, not the problem. Deleted outright once a sponsor funds a prize, because the prize needs a criterion.
**Domain-scoped prompt.** A theme plus a bounded domain: "build a tool that helps a small city publish its budget data". Cheap, real segmentation, and it still leaves the in-scope question open - which is precisely the question an organizer then answers forty times during the event.
**Structured statement.** The default. Context, the challenge as a question, constraints, resources provided, and a minimum viable submission. Skeleton below.
**Fully specified challenge.** A structured statement plus a starter repository, a dataset, and acceptance tests a submission either passes or does not. Organizer engineering work measured in days.
It buys near-perfect comparability, and it changes the event: teams execute a specification rather than choose a problem. Reserve it for long time boxes or for a sponsor whose integration tests already exist and can be handed over unchanged.
## The structured-statement skeleton
Five parts. A prompt missing any one of them is a domain-scoped prompt wearing a structured statement's formatting.
1. **Context** - two or three sentences on who has this problem and why it is not already solved. This is what stops teams building for a user who does not exist.
2. **The challenge, as a question** - one sentence, ending in a question mark. If it cannot be phrased as a question, it is a topic rather than a challenge.
3. **Constraints** - what the submission must do, must not do, and what platform or data it must work with. Keep these to things a judge could actually check.
4. **Resources provided** - datasets, API access, sample content, mentor availability, and where each is obtained. Name what is _not_ provided too; teams plan around absences they know about.
5. **Minimum viable submission** - the smallest thing that counts as a real entry. This is the part most briefs omit and the part that most changes team behaviour.
A good hackathon project is clearly articulated - a clear question or problem to solve, plus a reasonably specific proposed solution - and attainable, with easy onboarding for newcomers. Apply the twenty-minute onboarding test to any starter repo: the build environment can be spun up in less than 20 minutes.
That standard assumes participants pitching their own projects. When the organizer writes the prompt instead, every one of those qualities becomes the organizer's burden rather than the participant's.
## A worked pair
Both invented, and neither is an archived brief from a real event. The weak version is the shape a first draft usually takes.
**Weak - a topic formatted as a challenge:**
> **Sustainability Track.** We are excited to see what you build in the sustainability space! Use technology to make the world greener. Bonus points for creativity and impact. Best project wins.
What is wrong with it:
- no user
- no question
- no constraint a judge could check
- no resource
- no floor
"Bonus points" also leaks a weighting decision that belongs to `samber/dev-event-organizer-skills@hackathon-judging`, and "impact" names a category the brief never defined. Three teams will build carbon calculators and nobody will be able to say which one answered the prompt.
**Rewritten as a structured statement:**
> **Sustainability track - reducing waste in shared kitchens**
>
> _Context._ Shared kitchens in co-working spaces and student residences throw out food that is still good, mostly because nobody knows what is in the fridge or whose it is. The people running these spaces manage them by hand, on paper or in a group chat.
>
> _The challenge._ How can a small shared kitchen see what food it already has, and get it used before it spoils?
>
> _Constraints._ It must work for a space with no dedicated staff and no budget for hardware beyond a phone. Assume the people using it will not create accounts. Do not assume a network connection in the kitchen itself.
>
> _Resources provided._ An anonymised eight-week inventory log from two residences, and two mentors with facilities-management experience on Saturday afternoon. No barcode database - sourcing one is part of the problem.
>
> _Minimum viable submission._ Something a person can put one item into and get one useful signal back out of. A working single-flow demo counts. A design with no running code does not.
Why it works: a team can decide in one reading whether it wants this problem, what "done enough" means, and what it will show a judge. The constraints are checkable, and the absent resource is named.
## A real published example
NASA's Space Apps Challenge publishes a structured brief per challenge, archived by year at spaceappschallenge.org. The 2024 challenge "Leveraging Earth Observation Data for Informed Agricultural Decision-Making" ([spaceappschallenge.org](https://www.spaceappschallenge.org/nasa-space-apps-2024/challenges/leveraging-earth-observation-data-for-informed-agricultural-decision-making/)) runs a one-paragraph summary followed by three labelled sections: Background, Objectives, Potential Considerations.
> **Background** (excerpt). "Farmers around the world grapple with a myriad of challenges that threaten their livelihoods and food security... Innovative solutions that empower farmers to leverage data-driven insights from trusted resources - including NASA Earth data - are needed to tackle challenges related specifically to water."
> **The challenge, as published.** "Your challenge is to design a tool that empowers farmers to easily explore, analyze, and utilize NASA datasets to address these water-related concerns and improve their farming practices."
> **Potential Considerations** (excerpt). "You may (but are not required to) consider the following" NASA datasets grouped by topic - precipitation (IMERG), floods (OPERA, SAR), drought (Landsat, ASTER, ECOSTRESS), soil moisture (SMAP), and more - alongside open-ended concept prompts such as "Data Detective" and "Data Dashboard."
Measured against the five-part skeleton above:
- **Context** - present, and longer than "two or three sentences": Background runs four paragraphs and names why the problem persists ("past efforts... often struggled due to lack of a 'farmer-centric' design, limited stakeholder engagement, and inadequate scalability").
- **The challenge, as a question** - absent. NASA states it as an imperative, repeated near-verbatim in the summary and again inside Objectives, never as a question.
- **Constraints** - absent as a checkable bar. Potential Considerations is explicitly optional ("You may... consider") and reads as inspiration a team can take or leave, not a rule a judge could hold a submission against.
- **Resources provided** - present and itemized by topic, with a further Resources tab linking the full dataset and tool list.
- **Minimum viable submission** - absent. The brief widens the format instead of narrowing it: "You could make a storyboard, slide deck, a prototype, or something else."
Two of five parts are missing, and the two present run heavier than the skeleton's own weight budget. Read this as evidence for what the floor buys rather than a counter-example to it: NASA's challenge is judged across hundreds of local events by volunteer judges grading open-ended entries, where a wide format and no stated floor is a deliberate choice, not an oversight. An organizer without that reviewing capacity, or running one event rather than hundreds, needs the floor the skeleton asks for to keep entries comparable.
Smart India Hackathon runs the opposite shape. Its published problem statements (compiled from the official portal, e.g. a mirror at [gist.github.com](https://gist.github.com/VidhyaVarshanyJS/ee558d70f6278ee8a6c6e1375952e4ca)) carry six fields per entry - ID, title, technology bucket, category, description, submitting organization. Context, the ask and any constraint fold into the one Description field rather than separating out, and neither Background nor Expected Outcomes gets a column of its own.
Problem statement SIH1524, submitted by the Indian Space Research Organisation, states its ask inside that single field: "a secure DNS resolver that blocks resolution of malicious domain names" using threat-intelligence feeds, with "average DNS lookup time within 100 milliseconds". That is a real, checkable number delivered without a labelled Constraints section.
A reader still gets the skeleton's content, compressed into fewer and denser fields. The five-part shape is one way to carry this information, not the only way a real organizer has shipped it.
## Sizing ambition to the time box
One practitioner observation exists: _"Most projects will accomplish about 25% of what they think they can accomplish in the limited time they have."_
Name the quantity exactly. That is **25% of a team's own pre-hack estimate of its own scope** - a ratio of what a team delivers to what that same team predicted it would deliver. It is not a ratio against the organizer's prompt, not a completion rate against any external standard, and not tied to any stated duration.
The mapping from specificity to duration below is reasoned rather than measured. Apply it to your time box:
- **Under ~24 hours** - the minimum viable submission has to be genuinely small, and the resources have to be ready to use rather than ready to find. A team that spends four hours getting data is a team that spends a sixth of the event not building.
- **A weekend (~36-48 hours)** - the structured statement's natural home. Enough time for a team to choose an angle within the prompt, which is where the interesting divergence between submissions comes from.
- **A week or longer** - the fully specified rung becomes affordable and, for comparability, worthwhile. Teams have time to read acceptance tests and still build.
The one instruction that holds at every duration: name a minimum viable submission. It is what makes the quarter a team actually reaches into something demoable.
## Themed-event capacity planning
For a themed event where domain experts supply the problems, one ratio is worth knowing: maintain **one expert-plus-workable-project pairing per four non-expert participants.** It counts participants, not teams, and it counts expert-project pairs, not challenge tracks - do not silently convert it into a tracks-per-team ratio, which is different.
A themed event without enough workable projects splits into three groups, and the third is the failure the ratio exists to prevent: participants _"struggling to find something relevant to work on"_. The ratio comes from civic-tech events, where subject-matter experts arrive with domain problems that need translating into buildable projects. At a sponsor-API hackathon the equivalent expert is the sponsor's own engineer, and the ratio's purpose shifts from translating problems to unblocking integrations.
## Wording a sponsor prompt differently from a general one
A sponsor prompt has one extra job: it has to be a problem, not a product tour. Three differences from a general prompt:
- **State the constraint as a capability, not a brand instruction.** "The submission must persist data across sessions using the provided hosted store" beats "must use Sponsor X". The first is checkable and buildable; the second reads as an advertisement and produces integrations bolted on at hour thirty.
- **Publish the access path in the prompt itself** - where keys come from, what the rate limit is, and who to ask when it fails. Access friction is the single largest determinant of whether a sponsor track gets entries.
- **Publish the fallback.** State what happens to a team whose sponsor integration is unavailable through no fault of its own: judged on design and integration plan rather than a working call. Written in advance it is a rule; improvised during the outage it is a favour, and every team that already finished will say so.
One more, from the general rules rather than the sponsor: because a team may enter one project into several challenge tracks, a sponsor prompt should say explicitly that entering it does not forfeit the general prize. Teams assume the opposite, and the assumption suppresses entries.
references/rules-and-eligibility-source-text.md›
# Rules and eligibility: the adoptable set, its edits, and what it does not cover
Contents: the two source documents · what the set already covers · the fields you must edit · eligibility definitions · carve-out mechanics · the pre-existing-work rules · AI disclosure · intellectual property · what to check before adopting.
## Table of Contents
- [Why adopting beats drafting](#why-adopting-beats-drafting)
- [What the set already covers](#what-the-set-already-covers)
- [The fields you must edit before publishing](#the-fields-you-must-edit-before-publishing)
- [Eligibility definitions worth borrowing](#eligibility-definitions-worth-borrowing)
- [Carve-out mechanics](#carve-out-mechanics)
- [Intellectual property and ownership](#intellectual-property-and-ownership)
- [Check these before adopting anything above](#check-these-before-adopting-anything-above)
## Why adopting beats drafting
The source states its own licence to fork: _"Organizers can use these rules exactly or fork them and edit them to suit their needs."_ It also states the value being bought, in the organizer guide's own framing: clear rules help _"easily be able to point to specific rules if you have to disqualify hackers for cheating."_
That is the whole argument for the default rung in SKILL.md's rules menu. You are not saving writing time so much as inheriting the disputes somebody else already had.
## What the set already covers
Team and participation:
- _"Teams can be 1-4 people"_ - the copy-paste default. The 1 keeps solo entry open.
- The stated rationale, presented by the source as its own observation rather than as a study: _"We see hackers have the most success with teams of a maximum size of 4"_. Present it that way; it is a practitioner claim about team success, with no measured basis given.
- _"Organizers, volunteers, judges, sponsors, or anyone in any other privileged position at the event should not participate as a hacker."_
- _"All team members should actively participate in the event."_
Submission scope:
- _"You may not submit multiple projects"_ and _"You may submit to multiple challenges"_ - the pair that makes challenge tracks cheap. One project, many track entries.
- _"You may not crosspost to other hackathons"_ - the guide notes it generally recommends no but that the organizer should state it either way.
Work window and originality:
- _"You may not work on your project before the event. You must stop development when submissions are due"_, with the consequence spelled out: _"This means that you should not be reusing code from previous projects."_
- _"Teams can use an idea they had before the event."_
- _"Teams can work on ideas that have already been done. Hacks do not have to be "innovative"."_
- _"Teams can work on an idea that they have worked on before (as long as they do not re-use code or other project materials)."_
- _"Teams can use libraries, frameworks, or open-source code in their projects. Working on a project before the event and open-sourcing it for the sole purpose of using the code during the event is against the spirit of the rules and is not allowed."_
- _"Teams must stop hacking once the time is up. However, teams are allowed to debug and make small fixes to their programs after time is up."_ The source draws the line at a few lines of code; large changes or new features are not allowed.
The idea/code split is the useful structure here: an idea may be old, the code may not. That distinction is what lets a rule ban pre-built work without banning returning teams.
Code and artifacts:
- _"Your code must be available publicly (ideally in a git repository)."_
- _"Your code must remain public post event to be eligible for prizes. If your repo and video are not public, new winners may be selected."_
- The organizer guide's copy-paste version names a submission platform inside the sentence (_"You must submit your code in your Devpost submission as a publicly available link(GitHub link, repl.it, Google Drive link, etc). You should remove any API keys before sharing."_). The platform name is part of the quote, not a recommendation - the transferable requirements are a public link and key removal.
- _"You may use publicly available frameworks, but you need to list said frameworks in a readme."_
AI tooling, from the source's own dedicated section:
- _"Teams may use AI to assist them while coding, utilizing tools such as code completion, code generation, image generation, or other similar tools."_
- _"Teams should be honest and transparent about the AI code tools they used. This includes listing them in their project submissions and answering questions when talking to organizers, judges, and other hackers."_
- The organizer guide adds the enforcement half: a project should not be _"a reskin of an existing AI tool"_, and undisclosed use is grounds for disqualification and a report to the network.
Enforcement:
- _"Teams can be disqualified from the competition at the organizers' discretion."_ The next sentence gives a non-exhaustive grounds list: breaking the competition rules, breaking the code of conduct, or other unsporting behaviour.
## The fields you must edit before publishing
The source names three of these itself; the rest follow from the text. Adopting without editing them is the common failure, because the set arrives carrying another event's decisions.
1. **Team size.** The number is yours. Publish it and the solo-entry answer together.
2. **Hacking start and end times.** The source explicitly recommends adding _"specific start/end times for hacking"_ - the set ships without them.
3. **Eligibility scope and age.** The source states outright that _"The copy paste does not include age limit or demographic specific challenges."_ Its own copy-paste line reads _"This event is limited to students"_, which is wrong for most non-student events and must be replaced rather than deleted.
4. **Judging mode.** Its copy-paste line reads _"Judging will be in person."_ Replace it with whatever the format skill actually chose.
5. **Crossposting.** Decide yes or no, and state it either way.
6. **Public-code requirement.** Keep it only if your event can honour it. A corporate or client-data hackathon frequently cannot.
7. **The code-of-conduct link.** Point at your own document.
8. **The disqualification-reporting channel.** The source names its own network's address; yours must be a person or address you control.
## Eligibility definitions worth borrowing
The set defines "student" broadly rather than leaving it to interpretation, which is the transferable move:
> _"MLH Hackathons are primarily for students, but may also include professionals. MLH chooses to define students broadly. Anyone who attends a traditional school, college, or university, and those in bootcamps and similar programs are students. Those who graduated within the last 12 months are also considered students."_
Two things to copy: define every eligibility word that could be argued, and pick a numeric boundary where one exists (here, twelve months since graduation) rather than a vague one. Two things that do not transfer: the student framing itself, and the choice of twelve months, which is that network's number and not a standard.
## Carve-out mechanics
A demographic or skill-level challenge track composes with the base rules and needs its own wording. The procedural rule below is published; the fraction is yours to set.
- The published example: _"Example: Beginners track where at least half the team must have this be their first hackathon."_
- The rule that matters more than the example: _"Make sure to state how many of the team members must fit the category in your rules before the event."_
A carve-out needs four sentences to be enforceable:
1. who qualifies
2. what fraction of the team must qualify
3. how it is evidenced at submission time
4. what happens to a team that becomes ineligible when a member joins or leaves
The fourth is the one that gets skipped and the one that produces the argument.
## Intellectual property and ownership
The MLH rule set carries **no intellectual-property clause, no ownership assignment and no originality warranty.** Its only ownership-adjacent requirement is that submitted code be public and stay public to remain prize-eligible - which constrains visibility, not ownership.
Who owns work submitted to a hackathon is a jurisdictional legal question, not something a brief template settles. This skill therefore:
- writes no IP clause and recommends none;
- routes any sponsor request for IP terms to counsel via `samber/dev-event-organizer-skills@event-sponsor-agreement`, named in SKILL.md;
- treats "the participants keep their work" as an assumption to confirm, not a fact to publish.
If a brief needs an IP sentence, that sentence comes from a lawyer who has read the sponsorship agreement and the local law. A plausible-sounding paragraph written here would be the exact defect this skill was built to avoid.
## Check these before adopting anything above
- Does your event's culture actually permit public code?
- Is anyone under the age of majority expected, and does that change consent, prizes or photography?
- Does a sponsorship agreement already impose terms that contradict a rule you are about to publish?
- Does the code of conduct you link to have a working reporting channel and a named responder?
- Is any personal data collected at submission time, and does the brief say what happens to it?
Each one is a question to route, not a rule to write.
references/submission-checklist-and-categories.md›
# Submission checklist, deadline mechanics, and evaluation categories
Contents: how the demo format drives the checklist · the artifact list with wording · deadline and late policy · evaluation categories · the exclusion list.
## How the demo format drives the checklist
The demo/judging structure is chosen upstream and is a fixed input. It decides which artifact carries the judging, and the checklist follows from that rather than from a template.
| Chosen structure | What carries the judging | What the checklist requires | What it must not require |
| ---------------------------------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| Expo table (judges rotate through tables) | The live demo at the table | Code link, readme, a one-paragraph description, and the team present at its table for the whole window | A video, unless it is genuinely optional and says so |
| Stage pitch (teams present to a panel) | The live presentation | Code link, readme, description, plus whatever the stage needs - slide deck by a stated time, a named presenter | A separately judged video that competes with the pitch |
| Video only (async judging) | The submitted video and written description | Code link, readme, and a video whose length, content and availability constraints are all binding | Attendance at any live slot |
| Hybrid (expo round narrows to stage finalists) | Both, in sequence | The expo checklist for everyone, plus what finalists must add and by when | A finals artifact due before finalists are known |
The recurring mistake is a brief that requires a video at an expo-table event. Nobody watches it, teams spend an hour of the time box making it, and it becomes an unjudged obligation the rules still allow a team to be disqualified over.
## The artifact list, with wording
The requirements below are quoted or paraphrased from MLH's published rules. Each is stated in the source as an absolute requirement, not a suggestion.
**Code link:** _"Your code must be available publicly (ideally in a git repository)."_ And the durability half, which is the one teams break: _"Your code must remain public post event to be eligible for prizes. If your repo and video are not public, new winners may be selected."_
Say both halves in the brief. A team that makes its repository private the Monday after has broken a rule it never read.
Adoption check: the public-code requirement assumes a culture that is open by default. A corporate hackathon on internal data, or a client-confidential event, cannot honour it. Decide that before copying the sentence - and if you drop it, say what replaces it, because "submit your code" with no visibility rule is what produces a submission nobody can open.
**Key hygiene:** Remove API keys before sharing the link. Worth restating as a positive instruction rather than a prohibition - teams leak keys by forgetting, not by intending.
**Readme:** _"You may use publicly available frameworks, but you need to list said frameworks in a readme."_ The readme is also the cheapest place to require what the project does in two sentences, how to run it, and what is not finished. Judges read it when a demo fails.
**AI-tool disclosure:** _"Teams should be honest and transparent about the AI code tools they used. This includes listing them in their project submissions and answering questions when talking to organizers, judges, and other hackers."_ The enforcement half - a project should not be a reskin of an existing AI tool, and undisclosed use is grounds for disqualification.
This is the fastest-moving rule in any current brief. Write it as a disclosure requirement rather than a usage ban; a ban is unenforceable and a disclosure requirement is checkable in the readme.
**Demo video**:
- two minutes or less
- created during the event
- naming the hackathon at the start of the video
- remaining public afterwards to stay prize-eligible
The naming requirement exists to stop a video being reused across events, which is worth explaining in the brief so it does not read as bureaucracy. For fully digital events, this is the binding deliverable that carries the judging.
**Written description:** one paragraph, in the team's own words, saying what the project does and who it is for. It is what a judge reads before arriving at the table and what a sponsor reads when picking its own track winner.
## Deadline and late policy
- Set the deadline as a **wall-clock time in a named time zone**, never as "the end of hacking" or a duration. Teams in different rooms disagree about when hacking ended; nobody disagrees about 11:00 CET.
- Set it **before** the first judging slot, not at it. Judges need the submission list to exist before they start moving.
- State the late policy **before anyone is late**. Whatever it is (a hard cut, a grace window, a reduced eligibility) must be a rule in advance, not a favour afterwards.
- State what counts as submitted: the artifact exists at the link, and the link is reachable. A team that submitted a private repository has not submitted.
- The one published allowance worth mirroring: MLH's rule set permits debugging and small fixes after time is up but not new features or large changes. If you allow that, say where the line is; if you do not, say that instead.
## Evaluation categories
Name them in the brief. Do not weight, scale or total them - that belongs to `samber/dev-event-organizer-skills@hackathon-judging`, and a weight published here becomes a promise it has to honour or contradict.
One published set exists, each category with a written description of what a judge is looking for:
- **Technology**:
- how technically impressive the hack is
- whether the problem tackled was difficult
- whether a clever technique or many components were involved
- **Design** - whether the team thought about the user experience, and how well made the interface is, adapted per project type (visual craft for a website, interaction quality for hardware).
- **Completion** - whether the hack works, and whether the team achieved what it set out to.
- **Learning** - whether the team stretched itself and tried something new, explicitly rewarding a team that switched away from what it always builds.
Deliberately do not carry weighting into the brief; hand it to `samber/dev-event-organizer-skills@hackathon-judging` as an input, since the weighting decision is theirs.
Adapt the set rather than copying it. These four fit a learning-oriented student event - "learning" in particular rewards a behaviour a commercial hackathon may not care about. A corporate or sponsor-led event judging commercial viability needs a different list, and inventing categories that match the prizes is legitimate; inventing weights is not.
## The exclusion list
A published evaluation set explicitly excludes what its criteria do **not** include, with reasons:
- code quality
- pitch quality
- idea quality
- how well the project solves a real problem
One stated reasoning: _"How well you pitch. Hacking is about building and learning, not about selling."_
Publishing an exclusion list is the cheapest way to stop teams optimising for something nobody is scoring. Teams read the brief as a specification of how to win, and an unmentioned dimension gets guessed at.
Copy the shape, decide the content yourself. This particular list belongs to a learning-oriented event; an event that genuinely does judge commercial viability would exclude a different set, and copying these four exclusions unchanged would contradict its own prizes.
SKILL.md›
---
name: hackathon-brief-design
description: Write the hackathon challenge document teams read before they build - problem statements sized to the time box, thematic challenge tracks, the published rules and eligibility text, the submission-artifact checklist, sponsor-challenge framing, and naming (never weighting) the evaluation categories. Use whenever the user mentions a hackathon brief, challenge or track prompts, hackathon rules or eligibility, submission guidelines, or turning a sponsor's API into a challenge - even if they never say "brief". Challenge tracks here are thematic categories a team enters, not parallel session streams. Do NOT use for rubric weights and judging mechanics - use samber/dev-event-organizer-skills@hackathon-judging instead.
license: MIT
metadata:
author: Samuel Berthe
version: "1.1.0"
---
# Hackathon Brief Design
You write the document a hackathon hands its teams: what to build, under which rules, who may enter, what to submit, and what "good" will be called. It is the only artifact every participant reads, and every dispute at the ceremony traces back to a sentence it did or did not contain.
## What "track" means here
A **challenge track** is a thematic category a team enters its project into: an AI track, a sponsor's API track, a beginners track. It is a content and prize construct.
`samber/dev-event-organizer-skills@event-format-selection` uses "track" for parallel session streams, single-track versus multi-track programming. Same word, different concept.
Write **challenge track** wherever a reader could take the other meaning. A session-track decision settles nothing here.
## What you own, and what is already decided
You own the written brief:
- problem statements
- challenge-track content
- rules and eligibility text
- the submission checklist
- sponsor-challenge framing
- the _names_ of the evaluation categories
Three things arrive already decided. Publish them rather than re-open them.
- **The demo/judging structure** (expo table, stage pitch, video-only, or the two-stage hybrid) belongs to `samber/dev-event-organizer-skills@event-format-selection`. Translate it into the submission checklist and the deadline rather than pick it: a video-only event makes the video the deliverable, an expo event makes it optional. Deliverable format is downstream of that choice, never an independent one you make here.
- **Criteria weights, the scale, judge allocation, tie-breaks and disputes** belong to `samber/dev-event-organizer-skills@hackathon-judging`. That skill states the boundary from its own side: the evaluation categories named in the published brief are yours, and it weights them and builds the mechanics on top. Name the categories, and never print a weight, a scale or a points total.
- **Prize amounts, cash-versus-in-kind and payout handling** belong to `samber/dev-event-organizer-skills@hackathon-cash-prize`. Write "each challenge track awards a prize"; never write the figure.
Every ranking below is a default, not a law. Re-rank each menu after the interview against what you already know about this event:
- last edition's published rules
- a signed sponsorship agreement
- an organizer who has run this API before
- a beginner-heavy audience
## Interview
Ask one question at a time, multiple-choice where possible. Questions 3-5 and 8-9 decide which rung each menu defaults to; the defaults cannot be picked without those answers.
1. How long is the hacking window in hours, and is the event in person or fully digital?
2. Which demo/judging structure is already chosen? (Fixed input - do not re-decide it.)
3. Do participants bring their own problems to work on, or does the organizer supply the problem statements? Both is a real answer.
4. How many sponsors fund a prize, and does any signed agreement already promise a named challenge track?
5. Does any sponsor's API, dataset or hardware need keys or accounts - and has anyone on the organizing team actually built something small against it end to end? What happens to those teams if it goes down mid-event?
6. Who may enter and who is barred: students only, an age minimum, geography or employment exclusions, organizers and volunteers? And what team-size rule has `samber/dev-event-organizer-skills@hackathon-team-formation` already decided - a maximum, a minimum, solo entries allowed or not? (Fixed input you publish, not one you set. The pass threshold below counts it, so get the number before drafting.)
7. Is a demographic or skill-level carve-out required - a beginners track, a first-timers quota, a student-only category?
8. Do prizes carry cash value, are minors expected to attend, and is any personal data collected through the submission? (Decides whether the cheapest rules rung survives at all.)
9. What is the publication timeline and event cadence?
- When must the brief be published?
- Is this a one-off, or a recurring edition whose rules should still hold next year?
- What is the effort ceiling: organizer hours before publication, and whether counsel is available at all?
10. How narrow is the theme - one vertical, or open to any domain - and has anyone tested whether enough people want to build on it? (Decides whether § Theme demand test runs before the problem statements.)
Q9's three answers each move a named rung. Say which as you re-rank:
- A near publication date promotes the adopted standard rule set over anything drafted, and demotes the fully specified challenge, whose starter repo and acceptance tests are the longest lead time on any menu here.
- A recurring edition promotes the rungs written once and reused, the adopted set with its carve-outs and the per-track prompt skeleton, because their cost amortises across editions where a one-off pays it in full.
- An effort ceiling with no counsel behind it does not demote full legal-grade, it removes the route to it. Say so rather than substituting self-written legal-sounding text.
## Workflow
1. Run the interview. Read last edition's published rules first if one exists.
2. Fix the rules and eligibility text **before** the problem statements. It deletes rungs from the other menus and it carries the real exposure. Load [references/rules-and-eligibility-source-text.md](references/rules-and-eligibility-source-text.md).
3. Run the theme demand test when Q10 names a narrow theme (see § Theme demand test). Then decide the challenge-track structure, and write one problem statement per track. Load [references/problem-statement-patterns.md](references/problem-statement-patterns.md).
4. Convert each sponsor commitment into a track prompt or a bonus-prize criterion, and write the fallback sentence for a sponsor platform that fails.
5. Name the evaluation categories. Say plainly in the brief who weights them and when the weights get published, then hand the categories to `samber/dev-event-organizer-skills@hackathon-judging`.
6. Build the submission checklist from the chosen demo structure, never from a generic template. Load [references/submission-checklist-and-categories.md](references/submission-checklist-and-categories.md).
7. Run the ambiguity pass: for every rule, ask what a team arguing the opposite reading would point at.
8. Publish before registration closes, then freeze. A rule added after teams start building applies to a competition nobody entered.
Present the brief section by section for validation, never as one block:
- rules
- eligibility
- tracks
- problem statements
- submission checklist
- categories
Get explicit approval before publishing; publication is the point of no return.
If your harness has persistent memory, record:
- the published rule set and which fields were edited
- the specificity rung chosen per track
- the sponsor fallback sentences
- every question a participant actually asked during the event, the most useful of these, since each one names a sentence the next brief needs
- the theme demand checkpoint: date, self-set count, actual count, and whether the theme widened
- post-event outcomes per project (see § Measurement), re-checked at a self-set interval after the event
## Problem-statement specificity
Four rungs, from a bare theme to a fully specified challenge with a starter repo and acceptance tests.
**Size the ambition to the time box.** One practitioner rule of thumb circulates: "Most projects will accomplish about 25% of what they think they can accomplish in the limited time they have." Read the figure against the right denominator: it is 25% **of a team's own pre-hack estimate of its own scope**, not of the organizer's prompt, not of any absolute measure, and not a completion rate. It is one organizer's observation, not a measured rate.
The design consequence runs through every rung below: write each prompt so that the quarter a team actually reaches is itself demoable, by naming a minimum viable submission rather than leaving teams to discover one at hour forty.
- value (a team can self-assess whether it is in scope; judges can compare submissions to each other): `fully specified > structured statement > domain-scoped prompt > open theme`
- effort (organizer writing time before publication, plus keeping every prompt consistent with the rules): `fully specified > structured statement > domain-scoped prompt > open theme`
- efficiency: `structured statement > domain-scoped prompt > open theme > fully specified`
**Dominance check, re-derived: clean only by construction, and by-construction is never a pass.** Both axes run in the same order, so no pair exists where one rung has value greater than or equal to another's and effort less than or equal to it. Zero dominance relations exist, the check can catch no misordering here, and the efficiency line therefore rests entirely on the arguments below rather than on any verification.
- **Structured statement** - the default, in five parts: context, the challenge as a question, the constraints, the resources provided, and a stated minimum viable submission. It is the cheapest rung at which a team can answer "are we in scope" without asking an organizer, and the rung the submission checklist and the evaluation categories both derive from without further writing.
Its project-quality template asks that projects have "a clear question or problem they are trying to solve plus a reasonably specific proposed solution". That template assumes participants pitching their own projects, so when the organizer writes the prompt instead, the burden moves to the organizer.
- **Domain-scoped prompt** - one sentence naming a domain and nothing else. Real segmentation value for near-zero cost, but it leaves the in-scope question open, and that question generates the clarification traffic an organizer answers all weekend.
- **Open theme** - near-zero cost, and genuinely correct at events where participants bring the problems. Promotion condition, keyed to Q3: participants arrive with their own projects and pitch them, in which case the brief's job is to publish the pitch mechanic rather than the problem.
**Delete it, from this menu and from the axis lines above, as soon as any sponsor funds a prize** (Q4). A sponsor prize needs a stated criterion to attach to, and parking the open theme at the bottom quietly leaves that prize with nothing to award against.
Where the pitch mechanic is chosen, publish one refinement alongside it: require the pitch to state a problem, not a solution. A team pitching "we want to build X" commits to an approach before anyone has tested whether the problem is real; a team pitching "this target group has this problem, here is the evidence" leaves the approach open to whoever joins. Publish two things with it - a short evidence requirement (interviews, numbers, a lived account - whatever counts as evidence here) and a stated minimum before a team may move to building - and hand both to `samber/dev-event-organizer-skills@hackathon-team-formation` as content the pitch mechanic runs.
- **Fully specified challenge** - the starved option: top of value, top of effort, so efficiency never picks it. Building a starter repo, a dataset and acceptance tests is organizer engineering work measured in days.
Promotion condition, keyed to Q1 and Q5: a time box of a week or longer, **or** a sponsor whose own integration tests already exist and can be handed over as-is. Below roughly a weekend it also changes what the event is, turning a build into a graded exercise.
No source publishes a formula converting a specificity rung to an hour count. A second, independent source agrees on the direction and nothing more: guidance for writing AI/ML challenge prompts tiers them by complexity, and states plainly that its hardest tier - real-world systems, unpredictable data, enterprise-grade reliability - "often exceed[s] the standard 24-72 hour window and may be better suited to extended formats," while its lower tiers fit inside it. Never read it as a second data point for the same quantity as the 25% figure above; they measure different things.
## Theme demand test
The theme is a demand bet, and a narrow one can fail before any brief is read. A hackathon with a narrow vertical theme drew too few entrants. Roughly a month before the event, the team widened the theme and the event filled. One event, self-reported: read it as a reason to test demand, not as proof that wide themes always fill.
Run the test before publishing problem statements, not after:
1. **Set a checkpoint date** far enough ahead that a rewrite still fits: problem statements, sponsor prompts and promotion copy all change when the theme does.
2. **Set a self-set pre-registration count** for that date, from your own capacity and prior editions. Never borrow another event's number.
3. **Pre-agree the widening trigger** with organizers and theme sponsors before registration opens: below the count on the checkpoint date, the theme widens. Write down the wider theme now, so the decision is mechanical rather than a debate.
4. **Pre-agree what survives a widening.** A sponsor who funded the narrow theme keeps a sponsor challenge track inside the wider one; see the track structure below. Confirm that with the sponsor before the checkpoint, not at it.
5. **Freeze after the checkpoint.** The widening is the last theme change. Workflow step 8 still holds: nothing moves once teams start building.
Hand the checkpoint date and count to `samber/dev-event-organizer-skills@event-marketing-plan`, which owns registration targets. This skill owns only the theme consequence.
## Challenge-track structure
Four rungs: one unified challenge, general plus one sponsor track, general plus several sponsor tracks, fully partitioned (every sponsor, every demographic, plus an open track).
**Adding a challenge track does not split the field.** A team submits one project, and that one project may enter several challenge tracks; the standard rule set publishes both halves as adjacent text, "You may not submit multiple projects" and "You may submit to multiple challenges". Every team stays eligible for the general prize while entering the sponsor track too, so the marginal cost of a track is rules-consistency work, not lost submission density. This lever is routinely missed, and it is what makes every rung below affordable.
- value (sponsor satisfaction, audience segmentation, prize flexibility, a beginner's chance of placing): `fully partitioned > general plus several sponsor tracks > general plus one sponsor track > one unified challenge`
- effort (writing each prompt, keeping eligibility carve-outs consistent, and the cross-track submission rule): `fully partitioned > general plus several sponsor tracks > general plus one sponsor track > one unified challenge`
- efficiency: `general plus one sponsor track > general plus several sponsor tracks > one unified challenge > fully partitioned`
**Dominance check, re-derived: clean only by construction, and by-construction is never a pass.** Value and effort run in the same order across all four rungs, so no strict-dominance pair exists and nothing here was verified by the check. The argument above is the whole basis for the ordering.
- **General plus one sponsor track** - the default. The first sponsor track costs one prompt and one prize line, and it converts a sponsor from a logo into a challenge owner. It is also where the cross-track rule gets written once, which is the real cost.
- **General plus several sponsor tracks** - marginal effort per additional track _falls_, because the second track copies a pattern the first one paid for, while value keeps rising. Total effort still rises, which is why it sits below the default; the falling margin is why it sits above one unified challenge.
- **One unified challenge** - cheapest, and it leaves prize flexibility and sponsor value on the table. **Delete it, from this menu and from the axis lines above, as soon as any sponsor funds a prize** (Q4): with no named track the sponsor's prize has no published criterion, and awarding it becomes an improvisation at the ceremony.
- **Fully partitioned** - the starved option, top of both axes. Promotion condition, keyed to Q4 and Q7: enough sponsors that each funds its own prize **and** a demographic carve-out is already required, so the per-track eligibility wording has to be written anyway. Absent both, partitioning buys empty tracks and a prize nobody competed for.
**No published ratio scales track count to participant headcount.** The one sourced ceiling scales it to judging capacity instead: MLH's own guide says to aim for 3 tracks absent sponsor tracks and without an overall 1st/2nd/3rd placement, never 20 or more, and to raise the count only as far as the judges running deliberations can absorb without the panel turning chaotic. Treat sponsor and judge headcount, not participant headcount, as the variable this ceiling actually tracks.
**Demographic carve-outs are their own wording problem.** State the required fraction of the team before the event, and never adjudicate it after teams have formed. A published example is "Beginners track where at least half the team must have this be their first hackathon". Treat the fraction as the thing to decide; treat "half" as one event's number.
## Rules and eligibility rigor
Four rungs: minimal (a team-size cap plus a code-of-conduct pointer), an adopted standard rule set, adopted plus carve-outs, and full legal-grade text reviewed by counsel.
- value (disputes prevented, defensibility of a disqualification, sponsor and participant confidence): `full legal-grade > adopted plus carve-outs > adopted standard set > minimal`
- effort (drafting and review hours before publication): `full legal-grade > adopted plus carve-outs > adopted standard set == minimal`
- compliance cost, as the review each rung triggers and the reversibility it costs: `full legal-grade > minimal > adopted plus carve-outs > adopted standard set`
- efficiency: `adopted standard set > adopted plus carve-outs > minimal > full legal-grade`
**The `==` on effort is argued, not a dodge.** The minimal rung is not free: somebody still decides the team-size number, writes the sentence and links the code of conduct. Adopting a published set replaces that drafting with a handful of edits, because the source is explicitly offered for forking - "Organizers can use these rules exactly or fork them and edit them to suit their needs".
Both land in the same order of magnitude: under an hour. That equality is the only real bend on any menu in this skill, and it is what the check below runs on.
**Dominance check, re-derived: clean by care.** Exactly one strict-dominance relation exists: the adopted standard set has strictly higher value than minimal, equal effort, and strictly lower compliance cost, and the efficiency line honours it by ranking the adopted set first.
- Full legal-grade never dominates (top of every cost axis).
- Adopted-plus-carve-outs never dominates the adopted set (higher value but strictly higher effort).
- Minimal dominates nothing.
A wrong ordering here would have failed the check, so this pass carries information the other three menus' passes do not.
- **Adopted standard rule set** - the default, and the strongest single recommendation this skill makes. A published, forkable set already covers:
- team size
- crossposting
- one-project-many-tracks
- work-during-the-window
- pre-existing code and open-source use
- AI-tool disclosure
- public-code requirements
- who may compete
- disqualification grounds
Clear rules let an organizer "easily be able to point to specific rules if you have to disqualify hackers for cheating". [references/rules-and-eligibility-source-text.md](references/rules-and-eligibility-source-text.md) names the fields you must still edit; adopting the set without editing them is the common failure.
- **Adopted plus carve-outs** - promotion condition, keyed to Q6 and Q7: a demographic or skill-level track, an age minimum, or a geographic or employment restriction. Each carve-out is per-track wording that has to compose with the base rules without contradicting them, which is where the extra hours go.
- **Minimal** - **delete it, from this menu and from the axis lines above, as soon as any prize carries cash value or any sponsor funds one** (Q8, Q4). A prize with value turns a dispute into a claim, and nothing is then published to point at. It ranks second on compliance cost for the same reason: it triggers no review before the event and defers the whole review to the least reversible moment there is, the disqualification itself, in public, with prizes on the table.
- **Full legal-grade** - the starved option: top of value, top of effort, top of compliance cost. Promotion condition, keyed to Q8 and Q9: a prize pool large enough that a losing team retains counsel, or a sponsorship agreement imposing IP terms. Promote it by routing to actual counsel, never by writing legal-sounding sentences yourself.
**Two of Q8's answers are gates, not menu choices.** Minors expected to participate, and personal data collected through the submission, each carry an obligation the efficiency line has no vote on: the review happens before publication, by counsel or by whoever owns data protection for the organizing entity, whatever rung the ratio landed on.
An obligation determines the response; efficiency only orders the options that remain. The same holds for the code of conduct every rung points at: `samber/dev-event-organizer-skills@event-code-of-conduct` owns it, the brief links it, and it is never a rung to be traded against effort.
**On intellectual property, this skill states no clause and recommends none.** The MLH rule set carries no IP-ownership term and no originality warranty at all; its only ownership-adjacent requirement is that submitted code be public and stay public to remain prize-eligible.
Whether a team, an organizer, or a sponsor owns submitted work is a jurisdictional legal question. Route it to counsel through `samber/dev-event-organizer-skills@event-sponsor-agreement` when a sponsor asks for it, and never let a plausible-sounding sentence stand in for the answer.
## Sponsor-challenge integration depth
Four rungs: the sponsor named as prize funder only, an optional bonus challenge using its product, its technology required for one track, and its technology as the event's sole substrate.
**The axes here agree, and the disagreement cannot be manufactured.** The tempting counter-argument: a sole substrate costs _less_ prompt-writing than a required track, since there is no general track to stay consistent with. That is true, and it does not flip the axis - provisioning keys and mentors for every participant rather than for one track's entrants outweighs it. Say so rather than invent divergence.
- value (sponsor return and renewal likelihood - argued, not measured): `sole substrate > required for one track > optional bonus challenge > named funder only`
- effort (vetting the sponsor's docs, provisioning keys and accounts, coordinating mentors, writing a prompt inside the constraint): `sole substrate > required for one track > optional bonus challenge > named funder only`
- dependency risk (what breaks in the brief if the platform, keys, docs or rate limits fail mid-event): `sole substrate > required for one track > optional bonus challenge > named funder only`
- compliance cost, as the review each rung triggers and the reversibility it costs: `sole substrate > required for one track > optional bonus challenge > named funder only`
- efficiency: `optional bonus challenge > required for one track > named funder only > sole substrate`
**All four axes run in the same order**, so there is no pair with value greater than or equal and any cost less than or equal. The check catches nothing here, and the ordering rests entirely on the argument above.
**The dependency-risk axis is why this menu has four cost lines and not two.** Effort is what an organizer spends before the event; dependency risk is what the event loses if something outside the organizer's control fails during it. They move together here but they are not the same quantity, and only the second one can delete a rung on the day.
- **Optional bonus challenge** - the default: the sponsor's product is one path to a bonus prize, never the only path. Teams who cannot get a key still compete, so a platform outage costs one prize rather than the event.
- **Required for one track** - promotion condition, keyed to Q4 and Q5: the signed agreement already commits to a named challenge track, **and** somebody on the organizing team has built something small end to end against the sponsor's API before publication. Never promote on the sponsor's own claim that the docs are good.
- **Named funder only** - cheap and safe, and the rung that most often breaks a sponsorship promise. **Delete it, from this menu and from the axis lines above, when the signed agreement already promises a named challenge track** (Q4) - at that point it is a contract term, not a menu choice.
- **Sole substrate** - the starved option on efficiency, and the one rung a _different_ axis can remove outright. Promotion condition, keyed to Q4 and Q5: a single sponsor funds the whole prize pool and the event is billed as its event, **and** every Q5 confirmation is already in writing.
**Delete it, from this menu and from the axis lines above, when the sponsor cannot confirm in writing both a sandbox or offline fallback and rate-limit headroom for the expected team count** (Q5). Efficiency merely ranks it last; dependency risk is what makes it unshippable, and the two are separate findings - promotion never overrides the delete.
**Every sponsor-dependent prompt needs a published fallback sentence.** State in the brief what happens to a team whose sponsor integration is unavailable through no fault of its own: judged on its design and integration plan rather than on a working call. Written before the event it is a rule; improvised during the outage it is a favour, and every team that already finished will say so.
## Evaluation categories in the brief
Name the categories. Never weight them, scale them or total them: that is `samber/dev-event-organizer-skills@hackathon-judging`, and publishing a weight here creates a promise that skill then has to honour or contradict.
Print the elimination criteria alongside them. A binary knockout list disqualifies a submission outright, so it belongs next to the category names rather than inside the weighted rubric. Print it in full; `samber/dev-event-organizer-skills@hackathon-judging` decides its content.
One published category set is worth starting from, each category with a written description of what a judge is looking for:
- technology
- design
- completion
- learning
That set carries its own default weighting. Keep the weighting out of the brief and hand it to the judging skill as an input instead.
Publishing what is **not** judged is the underused half, each exclusion carrying its reason:
- how good the code is
- how well the team pitches
- how good the idea is
- how well the project solves a real problem
Teams optimize for whatever the brief names, so an exclusion list is the cheapest way to stop forty teams polishing slides. Copy the shape, and decide the content for your own event: a corporate hackathon judging commercial viability would exclude a different list.
## Submission guidelines
Derive the checklist from the demo structure chosen upstream, never from a template. A video-only event makes the video the deliverable and its constraints binding; an expo or stage event makes the video optional and the live demo carry the weight. Getting this backwards is how a brief requires a video nobody will watch, or omits the one artifact judging depends on.
Requirements worth adopting from MLH's published rules, all stated there as absolute rather than as suggestions:
- submitted code is publicly available, ideally in a git repository, and stays public after the event to remain prize-eligible
- API keys are removed before sharing
- libraries and frameworks used are listed in a readme
- AI-tool use is disclosed in the submission
For fully digital events the same source requires a demo video of two minutes or less, created during the event, naming the hackathon at the start, and remaining public afterwards.
**The public-code requirement does not transfer without thought.** It assumes an event whose culture is open by default, and a corporate or client-data hackathon may not be able to honour it at all. Decide that before copying the sentence.
Set the submission deadline as a wall-clock time in a named time zone, and say what happens to a late submission before anyone is late. [references/submission-checklist-and-categories.md](references/submission-checklist-and-categories.md) carries the full checklist per demo format, the deadline mechanics and the artifact-by-artifact wording.
## Failure modes
- **Weighting the categories in the brief.** Naming them is your job; weighting them is not, and a weight published here binds a sibling skill that has not yet done its arithmetic.
- **Picking the deliverable format.** Video-versus-live was settled by the format skill. You translate it. Choosing it again produces a checklist the judging plan cannot execute.
- **Confusing challenge tracks with session tracks.** They are different decisions owned by different skills, and a brief that borrows the session-track count as its challenge-track count invents categories nobody sponsored.
- **A rule added after building starts.** Teams built against the published text. A new rule mid-event re-scores whoever already finished.
- **A prompt with no minimum viable submission.** A team reaching a quarter of its own plan has nothing demoable, and the brief is what decided that.
- **A sponsor track written from the sponsor's marketing copy.** Marketing copy names benefits, not buildable constraints. Rewrite it as a problem, then have the sponsor confirm the rewrite.
- **Carve-out fractions adjudicated after teams form.** A required fraction - "at least half the team" - has to be published before people choose teammates, or the rule quietly excludes teams that already exist.
- **Adopting a published rule set without editing its event-specific fields.** The set arrives with somebody else's hacking hours, eligibility scope and judging mode in it.
- **Locking a narrow vertical theme with no demand test.** A narrow theme can fail to attract entrants until it is widened with weeks to go. Without a pre-agreed trigger, the widening becomes a late debate with sponsors while registration stalls.
## Measurement
Every gate below is self-set rather than an industry standard; say so when presenting it. Do not borrow a disqualification, invalid-submission, rule-dispute or completion rate from another event as a target: the numbers are not comparable across formats, sizes and audiences.
No platform or academic survey of the field publishes an aggregate disqualification or rule-dispute rate at all. The closest a named event gets is one organizer's own post-hoc count, posted publicly mid-controversy, of roughly a quarter of its submissions arriving as an idea with nothing built. That is one event, self-reported, defending one judging dispute, and not a figure to import anywhere else.
**Pass threshold (structural, one only):** before publication, all seven exist in writing with zero blanks.
1. the hacking window as start and end wall-clock times
2. the eligibility statement
3. the team-size rule
4. the per-track problem statement with its minimum viable submission
5. the submission checklist matching the chosen demo format
6. the named evaluation categories
7. the submission deadline with its late policy
Iterate until the count is seven.
**Ambiguity gate (before publication):** for each rule, name the reading a team arguing the opposite would use. A rule with a second plausible reading is not yet written.
Signals to record for the next edition (self-set):
- every clarification question asked during the event
- submissions rejected as invalid and why
- challenge tracks that drew no entries
Each one names a sentence the next brief needs, or a track that should not exist.
**Post-event outcomes as impact evidence (self-set).** Organizers report that their hackathons repeatedly produced companies, and that at least one community was born from a hackathon and grew from it. The report carries no count. Log, per edition:
- projects still active after a self-set interval
- companies founded from a hackathon team or project
- communities, meetups or recurring groups started by participants
- participants who came back as mentors, sponsors or organizers
Record each outcome with its source - the team said so, a public page shows it - and never a rate. Hand the log to `samber/dev-event-organizer-skills@event-sponsor-fulfillment` for the sponsor report and to `samber/dev-event-organizer-skills@event-debrief` for the impact record, and use it when writing the next brief's context paragraph. Ask participants at submission time whether they may be contacted later about what became of the project; otherwise the follow-up has no consent behind it.
## Invocation examples
- "Write the challenge brief for our 36-hour AI hackathon - two sponsor tracks and a beginners track."
- "Our sponsor wants their API used. How do we word that without breaking the event if it goes down?"
- "What rules and eligibility text do we publish, and what do we not write ourselves?"
- "Turn our chosen expo-table judging into a submission checklist and deadline."
- "We have a theme but no problem statements. How specific should they be for one weekend?"
Expected output: a publishable brief carrying
1. the rules and eligibility text with its edited fields listed
2. the challenge-track structure with the cross-track submission rule
3. one problem statement per track at a stated specificity rung, each with a minimum viable submission
4. sponsor framing with its fallback sentence
5. the named evaluation categories and the exclusion list
6. the submission checklist derived from the demo format, with deadline and late policy
Present it section by section for validation before publication.
## References
- [references/rules-and-eligibility-source-text.md](references/rules-and-eligibility-source-text.md)
- [references/problem-statement-patterns.md](references/problem-statement-patterns.md)
- [references/submission-checklist-and-categories.md](references/submission-checklist-and-categories.md)