idea-box

# Idea Box

## When to Use

- The user has an idea worth tracking across sessions and wants a persistent home for it that survives context resets.
- The user wants to drive an idea through a disciplined lifecycle (brainstorm → feasibility → ablation design → build/kill) instead of evaluating it once and losing the thread.
- The user invokes any of the `+new`, `+advance`, `+list`, `+show`, `+kill`, `+resurrect`, `+regen-index`, `+decide` commands prefixed with `idea-box`.
- The user `cd`s into their idea-box repo (typically `~/lab/idea-box`) and starts working on an idea.
- A producer skill (`idea-feasibility`, `ml-ablation-design`, `academic-deep-research`, `followup-analysis`, a reader skill) is invoked from inside an `./idea_box/<slug>/` working directory — its output should land at the canonical filename for that slot.

Do **not** use this skill to:

- Evaluate an idea's feasibility — that's `idea-feasibility`. Idea-box reads its output but does not replicate it.
- Design ablation experiments — that's `ml-ablation-design`. Idea-box reads its output to gate the `feasible → building` transition.
- Brainstorm ideas from scratch — that's `superpowers:brainstorming` or `office-hours`. Those skills write `idea.md` into idea-box at the end.
- Read a single paper / repo / blog — those are the reader skills. Idea-box only catalogs their outputs under `evidence/`.

## Core principles

- **Convention, not engine.** Idea-box defines a directory layout and a state machine. The actual work (feasibility, ablation, reading) is done by the existing skills, which write to canonical filenames.
- **Hard gates, no silent fallbacks.** Every state transition is gated by on-disk preconditions. If a precondition fails, refuse the transition and print the specific missing fact. Never paper over a gate failure.
- **Public skill, private data.** This skill ships in `tao-research-skills` (a public repo). Idea data lives in a separate private repo (e.g. `~/lab/idea-box`). The user `cd`s into the private repo before triggering the skill.
- **Killed is permanent.** Resurrecting a killed idea creates a new slug that links back via `## Origin`. This preserves the historical signal that the idea was tried and failed.

## Directory layout

The skill assumes the working directory contains (or will contain) `./idea_box/`. One subdirectory per idea:

```
./idea_box/
├── INDEX.md                              # generated, regenerated by +regen-index
└── <YYYY-MM-DD-idea-slug>/
    ├── idea.md                           # canonical normalized spec
    ├── STATUS.md                         # current_state + transition history
    ├── evidence/
    │   ├── arxiv/<paper-slug>.md         # from arxiv-latex-reader / pdf-reader
    │   ├── github/<repo-slug>.md         # from github-reader
    │   ├── blogs/<post-slug>.md          # from blog-reader
    │   └── models/<model-slug>.md        # checkpoint / model-card notes
    ├── feasibility.md                    # from idea-feasibility (gate input)
    ├── ablations.md                      # from ml-ablation-design (gate input)
    ├── followups.md                      # from followup-analysis (optional)
    └── decisions.md                      # append-only log; every override / kill reason
```

If `./idea_box/` does not exist, do **not** silently create it. Print:

```
no ./idea_box/ found in cwd. cd into your idea-box repo first
(typically: cd ~/lab/idea-box), then re-run the command.
```

This prevents accidentally writing into the wrong project.

## State machine

```
                ┌─ feasible ─┐
                │            ├─→ building ─→ built
explored ──────→┤            │              │
                │            │              └─→ killed
                └─ blocked ──┘
                     │
                     └─→ killed
```

States:

- `explored` — the idea is captured in `idea.md` but has not been feasibility-checked.
- `feasible` — `idea-feasibility` verdict is High or Medium.
- `blocked` — verdict is Low or Blocked with named blockers; the idea is on hold but not killed.
- `building` — has a feasibility pass AND an `ablations.md` plan AND a go-ahead in `decisions.md`.
- `built` — the MVP/ablations produced a result worth recording (commit, run id, eval number).
- `killed` — terminal. Never reused. Resurrecting means creating a new slug.

`built` and `killed` are terminal. The only way to "revisit" a killed idea is `+new` with a fresh slug and an `## Origin` section that names the dead slug.

## Hard gates

Every transition is gated by a list of must-be-true facts on disk. If any fact is false, the transition is refused and the skill prints the specific missing precondition.

| Transition | Hard gate (all must be true) |
|---|---|
| `*` → `explored` | `idea.md` exists with 5 frontmatter fields filled AND 5 spec bullets non-empty |
| `explored` → `feasible` | `feasibility.md` exists AND contains `### Verdict` block AND verdict ∈ {High, Medium} |
| `explored` → `blocked` | `feasibility.md` exists AND verdict ∈ {Low, Blocked} AND at least one named blocker |
| `blocked` → `feasible` | re-run `feasibility.md` with verdict ∈ {High, Medium} AND `decisions.md` has entry explaining what changed |
| `feasible` → `building` | `ablations.md` exists AND defines MVP with concrete minimum hardware AND `decisions.md` records the go-ahead |
| `building` → `built` | `decisions.md` has outcome entry referencing commit hash / W&B run id / eval number AND `INDEX.md` is regenerated |
| `building` → `killed` | `decisions.md` has kill entry naming the specific signal that failed |
| any → `killed` | `decisions.md` has kill entry with one-paragraph reason |

Refusal output example:

```
gate failed: explored → feasible
  needed: feasibility.md with verdict ∈ {High, Medium}
  found:  feasibility.md verdict = "Blocked"
  next:   either advance to `blocked` instead, or re-run idea-feasibility
          after addressing the named blocker(s).
```

## File schemas

### `idea.md`

```markdown
---
slug: 2026-05-18-flow-matching-text-encoder
created: 2026-05-18
goal_type: research-paper | student-project | prototype | product
language: en | zh
tags: [diffusion, text-encoder, flow-matching]
---

# <One-line title>

- **Problem:** ...
- **Mechanism:** ...
- **Target setting:** ...
- **Expected gain:** ...
- **Required dependencies:** checkpoint(s), code, dataset(s), GPU budget

## Origin

Where the idea came from (conversation, paper, observation) — 1-3 sentences.
```

The 5-bullet shape matches the `idea-feasibility` skill's "Normalize the idea" output, so feasibility runs can read `idea.md` directly instead of re-asking the user.

### `STATUS.md`

```markdown
---
current_state: explored | feasible | blocked | building | built | killed
last_transition_at: 2026-05-18T14:32:00+02:00
---

# Status history

- 2026-05-18T10:00 — created (explored)
- 2026-05-18T14:32 — explored → feasible (idea-feasibility verdict: Medium, gate passed)
```

Append one line per transition. Never delete history.

### `feasibility.md`

Verbatim output of `idea-feasibility`. Must contain a `### Verdict\n[High|Medium|Low|Blocked]` line so the gate can grep it. If the user runs feasibility multiple times, the most recent run overwrites this file and the prior run is preserved by appending a dated header in `decisions.md` ("re-ran feasibility on 2026-06-01 because X was released").

### `ablations.md`

Output of `ml-ablation-design`: ablation matrix, success/failure metrics, smallest-experiment plan.

### `decisions.md`

Append-only log. One entry = ISO timestamp + 2-4 sentences. Every override, every kill reason, every "we changed scope because X" goes here. This is the file the user reads in six months to remember why something died.

```markdown
## 2026-05-18T14:32 — feasibility complete

idea-feasibility returned verdict=Medium. Main blockers: dataset access (workaround:
use the synthetic route from §3 of the paper). Decided to advance to `feasible`.

## 2026-06-01T09:15 — kill

MVP loss diverged after 5k steps on the smallest configuration; kill-shot triggered.
Synthetic data route did not generalize. See evidence/arxiv/2403.12345.md for the
related-work discussion that explained why.
```

### `INDEX.md`

Generated by `+regen-index`. Never hand-edited.

```markdown
# Idea Box index

Last regenerated: 2026-05-18T14:32

| slug | status | last_touched | one-liner |
|---|---|---|---|
| 2026-05-18-flow-matching-text-encoder | feasible | 2026-05-18 | Replace T5 with flow-matched encoder in SDXL |
```

## Commands

The skill recognizes these prefix-style commands in natural-language prompts.

### `idea-box +new "<title>"`

Bootstrap a new idea.

1. Check `./idea_box/` exists. If not, refuse with the cwd error.
2. Generate slug: `<YYYY-MM-DD>-<kebab-case-from-title>`. Reject if it collides.
3. `mkdir -p ./idea_box/<slug>/evidence/{arxiv,github,blogs,models}`.
4. Write `idea.md` skeleton — prompt the user for the 5 bullets if not supplied.
5. Write `STATUS.md` with `current_state: explored`.
6. Create empty `decisions.md` with the creation entry.
7. Append one row to `INDEX.md`.
8. Print the absolute path of the new directory.

### `idea-box +list`

Render `INDEX.md` to terminal sorted by state (explored > feasible > blocked > building > built > killed) then by `last_touched` descending. Filters:

- `+list --state=feasible` — only feasible
- `+list --tag=diffusion` — only ideas tagged `diffusion`
- `+list --since=2026-04-01` — only ideas touched since that date

### `idea-box +show <slug>`

Summarize the idea:

- one-line title + current state + last_touched
- the 5 spec bullets from `idea.md`
- last 3 entries of `decisions.md`
- counts: how many evidence files of each type
- which gate(s) currently block the next forward transition

### `idea-box +advance <slug>`

Attempt a forward transition. Determine the next state from `STATUS.md.current_state`. Run all hard gates for that transition. On success: append a line to `STATUS.md` history, update `current_state` and `last_transition_at`, update `INDEX.md`, print the resulting state. On failure: print exactly which precondition was not met and stop.

If the current state has multiple forward edges (e.g. `explored` can go to either `feasible` or `blocked`), pick the one whose gate passes. If both gates can pass (impossible by construction but worth checking), refuse and ask the user.

### `idea-box +kill <slug> "<reason>"`

Always allowed. Append a kill entry to `decisions.md` (must be non-empty). Set `current_state: killed`. Update `INDEX.md`.

### `idea-box +resurrect <slug>`

Always refused. Print:

```
killed ideas stay dead. to revisit this thread:
  1. idea-box +new "<new title>"
  2. in the new idea.md, add an Origin section linking to <slug>
this preserves the signal that the original was tried and failed.
```

### `idea-box +regen-index`

Read every `./idea_box/<slug>/STATUS.md` and `idea.md`. Rebuild `./idea_box/INDEX.md` from scratch. Idempotent. Safe to run anytime. Used to recover from manual edits or merges.

### `idea-box +decide <slug> "<note>"`

Append a freeform entry to `decisions.md` without changing state. The escape hatch for "we learned X today" notes that don't trigger a transition.

## Cross-skill integration

Producer skills write into `./idea_box/<slug>/` at canonical filenames. **They do not need to know about idea-box** — the agent passes them the destination path. Idea-box only documents the contract.

| Skill | Canonical destination |
|---|---|
| `superpowers:brainstorming`, `office-hours` | `./idea_box/<slug>/idea.md` |
| `idea-feasibility` | `./idea_box/<slug>/feasibility.md` |
| `ml-ablation-design` | `./idea_box/<slug>/ablations.md` |
| `academic-deep-research` | `./idea_box/<slug>/evidence/arxiv/<paper-slug>.md` |
| `followup-analysis` | `./idea_box/<slug>/followups.md` and `./idea_box/<slug>/evidence/arxiv/*` |
| `idea-explore` | `./idea_box/<slug>/explore.md` (consumes `followups.md`, GitHub issues, and adjacent-lit deep research to propose new candidate ideas) |
| `arxiv-latex-reader` | `./idea_box/<slug>/evidence/arxiv/<paper-slug>.md` |
| `pdf-reader` | `./idea_box/<slug>/evidence/arxiv/<paper-slug>.md` (PDFs that are papers) or `./idea_box/<slug>/evidence/blogs/<slug>.md` (PDFs that are not) |
| `github-reader` | `./idea_box/<slug>/evidence/github/<repo-slug>.md` |
| `blog-reader` | `./idea_box/<slug>/evidence/blogs/<post-slug>.md` |

When the agent is in an `idea_box/<slug>/` working directory and the user invokes one of these producer skills, the agent rewrites the producer's default output path (which usually lives under `docs/`) to the canonical idea-box destination.

## Triggering

The skill activates on the prefix commands above and on phrases like:

- English: `idea box`, `idea-box`, `new idea`, `advance idea`, `list ideas`, `kill idea`, `idea status`, `idea lifecycle`
- Chinese: `想法箱`, `新想法`, `推进想法`, `列出想法`, `想法生命周期`

Before doing anything destructive (writing `STATUS.md`, appending to `decisions.md`, regenerating `INDEX.md`), confirm the cwd looks right:

1. `./idea_box/` exists as a directory.
2. The git remote of cwd is NOT `tao-research-skills` (this skill must never write idea data into the public skills repo).

If either check fails, abort with the cwd error message.

## Anti-Patterns

- **Writing idea data into `tao-research-skills/`.** This skill is public; idea data must live in a private repo. The cwd check above prevents this.
- **Auto-creating `./idea_box/` in the wrong cwd.** Silent creation in the wrong place is worse than a clear refusal. Always require the user to be in the right directory.
- **Bypassing a gate** ("the user said it's fine, just write `building` anyway"). The whole point of hard gates is that they're hard. If the user wants to skip a gate, they record an override entry in `decisions.md` *and re-run the gate*; the gate either now passes or it doesn't.
- **Mutating a killed idea in place.** Always fork to a new slug.
- **Re-implementing feasibility / ablation logic inside idea-box.** This skill is a workflow primitive. Producer skills do the actual work.
- **Skipping `+regen-index` after a manual edit.** `INDEX.md` is generated; if you change a `STATUS.md` by hand, regenerate the index in the same change.

## See Also

- `idea-feasibility` — Produces `feasibility.md`; consumed by the `explored → feasible/blocked` gate
- `idea-explore` — Producer skill that proposes new candidate ideas anchored to a seed paper; writes `explore.md` into the idea-box dir and seeds the next round of `+new` ideas
- `ml-ablation-design` — Produces `ablations.md`; consumed by the `feasible → building` gate
- `academic-deep-research` — Writes evaluated papers into `evidence/arxiv/`
- `followup-analysis` — Writes the citation cone of a seed paper into `followups.md`
- `arxiv-latex-reader`, `pdf-reader`, `github-reader`, `blog-reader` — Reader skills whose outputs land under `evidence/` when invoked from inside an idea-box directory
- `superpowers:brainstorming`, `office-hours` — Producer skills that create the initial `idea.md`
- `fail-fast-ml-engineering` — Shares the "no silent fallbacks, refuse loudly" stance that the hard gates enforce
- `memory-sync` — Sibling workflow primitive; idea-box is to ideas what memory-sync is to per-project memory