⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v1.7.0

decision-log

maga2010@maga2010⭐ 631 stars· last commit 1mo ago· 0 open issues

Writes every KEEP/CUT/DEFER/PIVOT scope decision into an append-only team log with rationale, author, and timestamp. Use after scope-knife or any time the team changes direction.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐⭐ 631 on GitHubGitHub ↗

Popular

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

🏁 Hackathon Run

Ship the demo, not the dream.

A decision-making and execution system for hackathon teams operating under time pressure. Fifteen skills, one workflow: clarify, prize-target, scope, time-box, build, verify, demo, judge, ship, recover, pivot, retro, decide-log.

CI Version License: MIT Stars npm version npm downloads GitHub release


The problem

A hackathon is not a coding problem. It is a time-pressure, decision-making, execution problem.

  • 23 hours in, you have 8 unfinished features.
  • The demo crashes on stage and you have 60 seconds to recover.
  • A judge asks "what's novel here?" and you have no answer.
  • Your README references API keys that you cannot ship.
  • Your teammate has been debugging the wrong thing for 4 hours.

Hackathon Run does not help you write code faster. It helps you make the right cut, at the right time, every time.


How it works

Fifteen skills, mapped to the hackathon lifecycle:

idea-clarify (pre) pivot (mid-build redirect) │ │ ▼ ▼ scope-knife ─► time-box ─► fast-verify ─► demo-coach ─► judge-sim ─► ship-pack │ │ │ │ │ │ └──────────────┴────────────┴──────────────┴─────────────┴────────────┘ │ │ │ │ │ │ stack-picker (cold-start) retro (post-event) │ │ │ │ team-roster (build start) recovery-runbook (anytime) │ │ demo-rehearsal (final 2h)

SkillWhenOutput
idea-clarifyOne-paragraph brief, no demo_goal yet(artifact only)
scope-knifeToo many ideas, no MVP consensus, clock shrinkingKEEP/CUT/DEFER classification + demo path
fast-verify"Will this demo work?"Step-by-step verification, stops at first failure
demo-coach30/60/90-second pitch, no clear narrativeFlow script + risk flags
judge-simPre-submission self-review0-5 rating across 7 dimensions + fix priorities
ship-packSubmitting now, worried about secretsREADME check, secret scan, packaging command
recovery-runbookDemo fails on stageP0-P3 severity, fallback strategy, 30-second script
pivotMid-build direction changeRe-runs scope-knife with new constraints
time-box"How much time for each stage?"Schedule + per-stage checkpoints
stack-picker"What stack should we use?"Recommendation + 30-min bootstrap walkthrough
retroAfter submission, want ratios + action list4 ratios + keep_doing/stop_doing/try_next_time
demo-rehearsalFinal 2 hours, want a timed mock runPer-segment score + fix list
team-rosterBuild phase, >2 KEEP features, roles unclearRole assignments + bottleneck + rescuer
prize-strategyMulti-track hackathon, picks which prize to chaseTarget prize + 3-5 positioning actions
decision-logEvery cut needs a recorded "why"Append-only decision record with rationale

Each skill is independently invokable. You can run any of them at any time without running the others.


Agent workflow

Hackathon Run works best when an agent treats it as a harness, not as a menu of one-shot prompts. Four roles keep long-running work moving without letting the same agent both build and approve its own output: an initializer sets up the first session, a planner writes the default-FAIL contract, a generator builds one feature per sprint, and an evaluator verifies it from a fresh context.

The runtime follows the production agent-loop pattern used by ChatGPT and the OpenAI Agents SDK: context is assembled from sessions, every input and output passes a guardrail, tools return observable results, the loop is bounded by budget, and every meaningful step is traced. It also follows Anthropic's long-running harness pattern: the first session initializes the environment, every later session reads PROGRESS.md + git log, and the operator can stop or steer the loop from the outside.

Production agent loop

flowchart LR
  User(["User / trigger"]) --> InGuard{"Input guardrail\npolicy + budget + schema"}
  InGuard -->|"reject"| Block(["Blocked\nrefuse + explain"])
  InGuard -->|"accept"| Context["Context assembly\nsession + plan + skill"]
  Context --> Loop{"Agent loop\nmax_turns + budget"}
  Loop -->|"next turn"| Reason["Reason\nchoose action"]
  Reason --> Tools["Tool invocation\nskills / scripts / MCP / shell"]
  Tools --> Observe["Observe\nstdout / files / tests / evidence"]
  Observe -->|"loop"| Loop
  Loop -->|"final"| OutGuard{"Output guardrail\nJSON Schema + evidence"}
  OutGuard -->|"reject"| Loop
  OutGuard -->|"accept"| Output(["Final output\nstate + evidence"])
  Context -. "read / write" .-> Session[("Session\nhandoff + memory")]
  Loop -. "trace" .-> Trace[("Trace\nevents / spans")]

Harness runtime architecture

The production agent loop is organized into six layers: interface, context, agent loop, hands, durable state, and operator control. Every layer writes to or reads from the durable state store so a fresh context window can resume without the previous conversation.

flowchart TB
  classDef state fill:#fff7ed,stroke:#ea580c,color:#7c2d12;
  classDef gate fill:#eff6ff,stroke:#2563eb,color:#1e3a8a;
  classDef trace fill:#f0fdf4,stroke:#16a34a,color:#14532d;

  subgraph Interface["Interface Layer"]
    User(["User / trigger"]) --> InGuard{"Input guardrail\npolicy / budget / schema"}
    InGuard -->|"reject"| Reject(["Blocked\nrefuse + explain"])
    InGuard -->|"accept"| ContextAssembly["Context Assembly\nplan + session + skill + progress"]
  end

  subgraph Context["Context Layer"]
    Session[("session.json\nhandoff")]
    Progress[("PROGRESS.md\nagent log")]
    Git[("git log\ncommit history")]
    ContextAssembly -. "reads" .-> Session
    ContextAssembly -. "reads"

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/decision-log/SKILL.md3.3 KBupstream ↗
    ---
    name: decision-log
    description: Writes every KEEP/CUT/DEFER/PIVOT scope decision into an append-only team log with rationale, author, and timestamp. Use after scope-knife or any time the team changes direction.
    when_to_use: |
    Trigger when the user says "log the decision", "record the cut", "why did we cut X", or right after scope-knife classifies a feature. Do not invoke before scope-knife; without a decision there is nothing to log.
    
    
    version: 1.0
    category: lifecycle
    tags: ["append-only", "audit-trail", "keep-cut-defer-pivot"]
    dependencies: ["scope-knife"]
    side_effects: ["decision-log"]
    triggers: ["log a decision", "record what we decided", "decision history", "keep cut defer", "append-only"]
    ---
    
    # decision-log
    
    The retro can only teach you what the team remembers, and the team forgets by minute 90. decision-log makes the memory durable: every scope decision is appended with its rationale so the "why" survives to the retrospective and the next hackathon.
    
    ## Input contract
    
    Required:
    
    - `feature`: string — the feature or subject being decided (e.g. "Notifications")
    - `classification`: enum — `KEEP`, `CUT`, `DEFER`, or `PIVOT`
    - `rationale`: string — one sentence explaining why
    
    Optional:
    
    - `author`: string — name or handle of whoever made the call
    - `relates_to`: string — state file this decision relates to (default `plan.json`)
    - `out_dir`: path — where `.hackathon/` lives (default `.hackathon`)
    
    ## Execution
    
    ### 1. Capture the decision
    
    When scope-knife emits a classification, or the team changes direction mid-build, ask:
    
    - What is the feature or subject?
    - Which classification: KEEP, CUT, DEFER, or PIVOT?
    - What is the one-sentence rationale?
    
    ### 2. Append to the log
    
    ```bash
    python3 skills/decision-log/scripts/log_decision.py \
      --feature "Notifications" \
      --classification CUT \
      --rationale "Off demo path; removed for time." \
      --author alice
    ```
    
    The script never overwrites: it reads the existing `decision-log.json`, appends the entry, and writes it back.
    
    ### 3. Emit the transcript
    
    The script also writes `.hackathon/artifacts/decision-log.md` with every decision in reverse chronological order, ready to paste into the retro or a handoff doc.
    
    ## Output contract
    
    - `.hackathon/state/decision-log.json` — append-only record (matches `decision-log.schema.json`)
    - `.hackathon/artifacts/decision-log.md` — human-readable transcript
    
    ## Acceptance criteria
    
    - [ ] Every entry has `at`, `feature`, `classification`, and `rationale`.
    - [ ] `classification` is one of KEEP / CUT / DEFER / PIVOT.
    - [ ] Append mode never replaces existing entries.
    - [ ] `decision-log.json` validates against `decision-log.schema.json`.
    - [ ] Transcript lists decisions newest-first.
    
    ## Failure modes
    
    - `rationale` empty -> refuse; a decision without a reason is not a decision.
    - `classification` not in enum -> refuse; ask for KEEP/CUT/DEFER/PIVOT.
    - Existing log with mismatched `version` -> refuse; do not clobber a newer log.
    - Nothing to log (no decision made) -> suggest `scope-knife` first.
    
    ## Trigger phrases (for agent intent matching)
    
    - "log the decision"
    - "record the cut"
    - "why did we cut X"
    - "decision log"
    - "add a KEEP"
    - "we changed direction"
    
    ## See also
    
    - scope-knife (makes the decision; decision-log records it)
    - retro (reads the log to explain the journey)
    - team-roster (assigns who is accountable for each decision)
    
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/maga2010-hackathon-run-skills-decision-log.md

// REPO STATS

631 stars
0 open issues
Last commit: 1mo ago