idea-box

name

idea-box

description

Use when promoting an idea from a fleeting thought into a tracked artifact with a lifecycle. Defines a per-idea on-disk directory (./idea_box/<slug>/) and a hard-gated state machine (explored → feasible/blocked → building → built/killed) that the existing reader/evaluator skills (idea-feasibility, ml-ablation-design, academic-deep-research, followup-analysis, arxiv-latex-reader, pdf-reader, github-reader, blog-reader) plug into. Public repo ships only the convention; idea data lives in the user's private idea-box repo. Triggers: "idea box", "idea-box", "new idea", "advance idea", "list ideas", "kill idea", "想法箱", "新想法", "推进想法", "列出想法"

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 cds 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 cds 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

---
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

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

## 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.

# 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