Idea First

Idea-First Protocol

Idea-first is the entry point of the self-organizing skill chain. Runs right after the task is created, before any technical analysis.

Why: without an explicit definition of the task type the next skills are built on guesses — arch-first decomposes a fix into blocks when audit-first was needed, library-first looks in a non-existent layer, the agent goes into code when habit design is required.

Idea-first closes this gap with a 5-10 minute dialog.

Key principle: idea-first does not read code — it determines the task type through dialog. Code is read by the next skills.

Input

A new task description just registered by the fast-track flow.

Output

idea-first-{N}.md fixing the task type (product / feature / fix) and scope, after 5-7 discovery questions and user approval.

Hands off to

habit-first (product), arch-first (feature), or audit-first (fix), based on the classified type.

---

Step 0 — Check task context

Ensure {log_dir} and {slug} are known.

If not — run resolver (list recent tasks, prompt user), then continue.

Cannot skip. Without {log_dir} the artifact will not be saved.

---

Step 0.5 — Hot-fix exception

If the task is an obvious small edit (one line, a typo, a known problem with a known fix) — skip all of idea-first and go straight to execute.

Signs of a hot-fix

| Sign | Example | |---|---| | One line / one value | Change timeout from 30 to 60 sec | | Typo / formatting | Fix a typo in a button label | | Known fix for a known problem | Remove a duplicate in SQL you added yourself | | Time to complete 🔗 Task: {log_dir}/task.md

Idea-First — {N}.{R}

Date: {date} Task: {slug}

Type

{product / feature / fix} — {subtype if any}

Scope

{1-2 sentences}

Out of scope

{what we don't do}

Discovery answers

| # | Question | Answer |

Next skill

{habit-first / arch-first / audit-first} — because {rationale}

Register in task_artifacts + append row to `## Task files` in task.md.

---

## Step 5 — Route to the next skill

After writing the artifact — **automatically** invoke the next skill per type. Do not ask.

| Task type | Next skill | What it does |
|---|---|---|
| New product | `Skill('habit-first')` | Designs habit loop → outputs Habit Brief → hands off to arch-first |
| New feature | `Skill('arch-first')` | Decomposes into blocks → pins decisions |
| Fix / problem | `Skill('audit-first')` | Audit across 6 planes → gap table |

Context (`{log_dir}`, `{slug}`, artifact path) is passed via session — the next skill picks it up at Step 0.

---

## Anti-patterns

### ❌ Guess the task type from the title without questions

Received "migration logic" → decided "feature, going to arch-first" without discovery. The user meant a fix of an existing migration mechanism.

**Rule:** 5-7 questions (or 2-3 shortened) mandatory. Type derived from answers, not the title.

### ❌ Move to the next skill without type approval

Determined type → immediately called `Skill(arch-first)` without showing calibration. The user had no chance to correct.

**Rule:** Step 3 (calibration + approval) is mandatory. Explicit "ok" before Step 4.

### ❌ Read code inside idea-first

Asked 2 questions and went to grep the project structure "to understand better". That's the job of flow-first / audit-first.

**Rule:** idea-first works only through dialog. No Read / grep / find. Code reading in the next skills.

### ❌ Ignore the hot-fix exception

One-line config change. Agent honestly asked 7 questions, wrote an artifact, called arch-first. 30 minutes on a five-second edit.

**Rule:** Step 0.5 hot-fix exception — always check. Obvious one-step edit → skip idea-first.

### ❌ Inlining the skill instead of Skill()

Agent received task → executed idea-first protocol manually from memory, without `Skill()` tool. Outdated / incomplete protocol version, no accuracy guarantee.

**Rule:** always launch via `Skill('idea-first')`. Never imitate inline.

---

## Related skills

- **habit-first** — designs the habit loop for new products; invoked from idea-first for the "product" branch
- **arch-first** — decomposes features into blocks; invoked for "feature"
- **audit-first** — scans across 6 planes for fixes; invoked for "fix"
- **ship-first** — closes the task at the end; also handles the hot-fix short-path finalization

---

## Step 99 — Log invocation

```bash
sqlite3 {routing_db} \
  "INSERT INTO skill_invocations (task_id, block_num, skill_name, invoked_at)
   VALUES ('{slug}', '{N}', 'idea-first', datetime('now'))" 2>/dev/null || true

If {slug} / {N} unknown → hook writes empty; || true guards failure.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bearded-illirian
• Source: bearded-illirian/trailmark
• License: MIT

Install and usage instructions live in the source repository linked above.