# decision-log

Adopt this skill: https://proskills.md/skills/lifecycle/maga2010-hackathon-run-skills-decision-log

Page: https://proskills.md/skills/lifecycle/maga2010-hackathon-run-skills-decision-log
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/decision-log/SKILL.md
size: 3401
upstream: https://github.com/maga2010/hackathon-run/blob/main/skills/decision-log/SKILL.md

````text
---
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)
````

## File: README.md
upstream: https://github.com/maga2010/hackathon-run/blob/main/README.md

````text
# 🏁 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](https://img.shields.io/github/actions/workflow/status/hackathon-run/hackathon-run/ci.yml?branch=main&label=CI)](https://github.com/hackathon-run/hackathon-run/actions)
[![Version](https://img.shields.io/github/package-json/v/hackathon-run/hackathon-run?label=version)](CHANGELOG.md)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Stars](https://img.shields.io/github/stars/hackathon-run/hackathon-run?style=social)](https://github.com/hackathon-run/hackathon-run)
[![npm version](https://img.shields.io/npm/v/@hackathon-run/hackathon-run.svg)](https://www.npmjs.com/package/@hackathon-run/hackathon-run)
[![npm downloads](https://img.shields.io/npm/dm/@hackathon-run/hackathon-run.svg)](https://www.npmjs.com/package/@hackathon-run/hackathon-run)
[![GitHub release](https://img.shields.io/github/v/release/hackathon-run/hackathon-run.svg)](https://github.com/hackathon-run/hackathon-run/releases/latest)

<p align="center">
  <img src="docs/assets/images/hero.svg" alt="Hackathon Run hero" width="800">
</p>

---

## 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)        `

| Skill                | When                                              | Output                                              |
| -------------------- | ------------------------------------------------- | --------------------------------------------------- |
| **idea-clarify**     | One-paragraph brief, no demo_goal yet             | (artifact only)                                     |
| **scope-knife**      | Too many ideas, no MVP consensus, clock shrinking | KEEP/CUT/DEFER classification + demo path           |
| **fast-verify**      | "Will this demo work?"                            | Step-by-step verification, stops at first failure   |
| **demo-coach**       | 30/60/90-second pitch, no clear narrative         | Flow script + risk flags                            |
| **judge-sim**        | Pre-submission self-review                        | 0-5 rating across 7 dimensions + fix priorities     |
| **ship-pack**        | Submitting now, worried about secrets             | README check, secret scan, packaging command        |
| **recovery-runbook** | Demo fails on stage                               | P0-P3 severity, fallback strategy, 30-second script |
| **pivot**            | Mid-build direction change                        | Re-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       |
| **retro**            | After submission, want ratios + action list       | 4 ratios + keep_doing/stop_doing/try_next_time      |
| **demo-rehearsal**   | Final 2 hours, want a timed mock run              | Per-segment score + fix list                        |
| **team-roster**      | Build phase, >2 KEEP features, roles unclear      | Role assignments + bottleneck + rescuer             |
| **prize-strategy**   | Multi-track hackathon, picks which prize to chase | Target prize + 3-5 positioning actions              |
| **decision-log**     | Every 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

```mermaid
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.

```mermaid
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"
````
