ai4kanban 0.4.1

package/skill/references/add-task.md

@@ -0,0 +1,79 @@
+# Add a task
+
+Turn an idea into a card on the board. 
+
+1. **Resolve the modules.** If the modules are not explicitly given, infer them
+   yourself: read `docs/kanban/modules.md` and decide which modules the idea
+   touches. Never ask the user which modules to use.
+   If no module fits, repair `modules.md` according to `references/module-map.md`.
+2. **Scaffold, then write the body.** Run `create --title "..." --track <track>
+   --modules <the step-1 modules>` plus any other meta flags (see "The script" in
+   `SKILL.md`) writes the file, its frontmatter, and the README entry. 
+
+## Tightly coupled tasks go in one group
+
+If the request needs several tasks that only make sense together, make them a **group
+task** instead of loose cards.
+
+Example: "build a plugin system with a Slack and a Notion
+demo plugin" → 4 ids: a group root for the plugin system + a subtask for the
+system + a subtask for the Slack plugin + a subtask for the Notion plugin.
+
+See "## Group task" in `SKILL.md` for the folder layout and how to allocate the ids.
+Cards that stand on their own stay loose.
+
+## Don't split off near-duplicates
+
+If the new card is mostly a tweak, reframe, or extra detail on an upstream card that
+**isn't built yet**, update the upstream card instead. A card earns its own id only
+for genuinely separate work — a different file, system, or deliverable.
+
+## Scaffold the card
+
+Every meta field comes from a `create` flag. The frontmatter is not hand-editable — pass
+the fields to `${KB} create`:
+
+`--blocked-by` and `--related` are optional, based on the task dependencies.
+
+```
+${KB} create --title "Continue a run's conversation instead of copying its id" \
+             --track features --priority med --roi med --modules local-ui
+
+${KB} create --title "Stop saving a card's implementing stage" --track features \
+             --priority med --roi high --modules local-ui,skill --related 58
+
+${KB} create --title "Add a GitHub Projects storage backend for the board" \
+             --track features --priority low --roi med --modules skill,local-ui \
+             --blocked-by 55,61 --related 57
+```
+
+A new card carries no open questions — that's refine's job (`references/refine.md`).
+
+Got a field wrong, or learned something after the fact? `${KB} update <id> --priority low`
+— never an editor.
+
+## Write the card's body
+
+Replace the template — the summary line, `## Scope`, and `## Todo` only.
+
+The body is what you write. The shape is rough, not a strict form. Keep lines short and
+plain — a non-native reader skimming should get each line in one pass. Add any section
+that helps; drop any that doesn't.
+
+```
+<one short line: what to do and why it matters.>
+
+## Scope
+- <the concrete steps>
+
+## Todo
+- [ ] <one step you can check off>
+- [ ] <…>
+```
+
+- **title** lives in the frontmatter — one source of truth, so no `#` H1 in the body.
+- **Todo** (REQUIRED): the scope split into single-line steps you can check off, in order.
+- **Pushback** — add a `## Pushback` section only if something feels off: too much
+  work for the value, not worth doing now, or a risk to users.
+
+This isn't a full plan, just enough to start.

package/skill/references/auto-refine.md

@@ -0,0 +1,32 @@
+# Auto-refine
+
+Loop refining a card (`references/refine.md`) **and resolving its open questions** (`references/resolve.md`),
+until any of the conditions is met:
+1. status !== "todo"
+2. all todos checked
+3. questions.length > 0 && every question tag === "user"
+
+## Question tags
+
+Each open question in the card's `questions` frontmatter carries a tag saying who owns it:
+
+- **`[user]`** — a judgment call the agent must not guess: taste, priorities, money,
+  product direction.
+- **untagged** — freshly raised, not yet triaged. These are what a pass works through.
+
+Set tags with the script — never hand-edit frontmatter:
+
+```
+${KB} tag <id> 1,2,3 user               # tag several questions at once (comma-separated)
+```
+
+## The loop
+
+Never pause to ask the user.
+
+1. Run `references/refine.md`.
+2. If questions is not empty, spawn a subagent and hand it the card and the whole batch
+   of untagged questions at once. Questions should be answered with a fresh context.
+   It researches and decides according to `references/resolve.md`:
+   If answering surfaces new questions, add them untagged and run one more subagent for
+   the new batch.

package/skill/references/document-feature.md

@@ -0,0 +1,31 @@
+# Document a change
+
+A shipped change nobody can find is a change that doesn't exist. So every card that ships
+something a user can **see or do** carries todos to update the docs it touches, and it
+isn't done until they're written. Pick the surfaces the change actually touches — most
+touch one, some touch none. If it touches none, say why on the card.
+
+Write each doc update as its own todo, so it's checked off before the card is archived.
+
+## Surfaces
+
+Map the change to the reference docs your project keeps (see the skill's Configuration).
+Common surfaces — use the ones you have:
+
+- **User-facing docs / guides** — how a user does the thing. Add or update a guide when
+  the change gives the user a **new action, setting, or step**. Without this the user
+  never learns the capability is there. This is the default surface: most user-visible
+  changes need it.
+- **Landing / marketing copy** — what a **prospect is shown or promised**. Update it when
+  the change adds a capability worth advertising, a new surface, or a headline claim.
+  Write the change **into the doc only** — don't touch the landing page code unless the
+  card says to. The user reviews the doc first, then decides whether to ship it.
+- **Pricing / plans / limits** — update when the change **moves what a tier offers** — a
+  new limit, a feature moved between tiers, a new plan, or any price change. Keep the doc
+  in sync with what the code actually enforces.
+- **Roadmap / direction** — update only for a **direction-level shift** (positioning, the
+  core layers, monetization). A normal change does not belong here; reach for it only when
+  the direction itself moves.
+
+If your project keeps none of these docs, this step is a no-op — note that on the card and
+move on.

package/skill/references/local-ui.md

@@ -0,0 +1,34 @@
+# Run the board locally (ai4kanban-ui)
+
+An optional Next.js app that shows the board and drives the work from buttons instead of the
+terminal. The board works fully without it; set it up only when you want the buttons. The
+markdown files in `docs/kanban/` stay the single source of truth.
+
+**This page is setup only — how to get it running.** Using it (what each button does, group
+tasks, the Configuration dialog) is documented with the app itself:
+<https://www.npmjs.com/package/ai4kanban-ui>, or `kanban-ui/README.md` in its repo.
+
+## Run it
+
+From your repo root (the folder that holds `docs/kanban/`):
+
+```
+npx ai4kanban-ui        # http://localhost:7420
+```
+
+Localhost only. It ships a prebuilt server (nothing to compile) and finds the board by
+walking up to the first `docs/kanban/todo/`. Options:
+
+```
+npx ai4kanban-ui --board ../my-repo   # a board elsewhere (or set KANBAN_BOARD_DIR)
+npx ai4kanban-ui --port 4000          # a different port
+```
+
+There's nothing to install — `npx` fetches the package and caches it. To pick up a newer
+release, run it once as `npx ai4kanban-ui@latest`; later plain `npx ai4kanban-ui` runs
+reuse that. (Prefer a permanent command? `npm install -g ai4kanban-ui`, then run
+`ai4kanban-ui`, and `npm update -g ai4kanban-ui` to upgrade.)
+
+Nothing else to set up: the app keeps its own settings next to the board, and creates them
+when it first needs them. What those settings are, and what the buttons do, is in the app's
+guide (linked above).

package/skill/references/module-map.md

@@ -0,0 +1,29 @@
+# The module map
+
+Write and repair `docs/kanban/modules.md` — a plain list of the project's modules.
+
+A module is anything maintained in the codebase that grows independently. Judged by
+meaning, not by folder; a handful of lines, not one per folder. (Not a track: a track
+is a kind of effort, a module is a part of the product — a task has both.)
+
+## Example
+
+A repo with `server/`, `packages/core/`, `web/`, `cli/`, and `docs/` might map to:
+
+```
+If a line here disagrees with the repo you just read, fix the line.
+
+- **api** — the backend server and its shared core. `server/`, `packages/core/`.
+- **web-app** — the browser app users sign into. `web/`.
+- **cli** — the command-line client. `cli/`.
+- **docs** — the public documentation site. `docs/`.
+```
+
+Five folders, four modules — the server and its core always change together, so they
+are one line.
+
+## Repair
+
+Whoever reads the map and sees it disagree with the repo fixes it in the same run: add
+the missing line, delete or rename the dead one, fix a stale path. If the user says the
+map is wrong, rebuild from scratch.

package/skill/references/presets/indie-hacker.md

@@ -0,0 +1,24 @@
+# Preset: indie-hacker
+
+For a solo or small-team product you're trying to launch and grow. Replaces the default
+tracks with a growth-weighted three-track model, and adds two review gates (moat, trust)
+plus a market-validation method.
+
+To use this preset, set `PRESET: indie-hacker` in `docs/kanban/config.md` and copy the
+three track values below into the `TRACKS` field.
+
+## The three tracks
+
+- **growth (50%)** — get in front of users: SEO posts, outreach DMs, posts on
+  X / Reddit / LinkedIn / 小红书, YouTube, Product Hunt, G2. Suggest growth methods worth
+  trying. If you keep a content pipeline, draft a writer-ready plan first.
+- **validation (30%)** — check the market wants a feature before building deep. Use it for
+  roadmap features not built yet, and for built features uncommon in the market. Method:
+  post an honest, unbiased question on Reddit / X, or share a free trial on a
+  build-in-public community. To run a Reddit validation, follow
+  `references/presets/validate-on-reddit.md`. Save results to `docs/validations/<name>.md`
+  (or wherever you keep them). Skip subjective tests ("ask your mom").
+- **building (20%)** — stay at MVP; don't over-build. Build when it: scales internal work
+  an agent can own, strengthens product positioning, or is strongly demanded by users.
+  Building is the trust load-bearer — without it you can't convert, so building blockers
+  gate the launch.

package/skill/references/presets/validate-on-reddit.md

@@ -0,0 +1,82 @@
+# Validate a move on Reddit
+
+Use for a **validation** task that says to test a product decision, feature, or
+move by posting to Reddit before building.
+
+You draft the Reddit posts and scaffold the results doc. The user posts manually
+and pastes replies back; then you write the verdict.
+
+## Steps
+
+1. **State the goal** — what decision the replies should inform. Soft criteria
+   are fine; judge the verdict yourself when replies come in.
+2. **Follow the post style** (below).
+3. **Draft the probes** that fit. Common ones:
+   - **Discovery** — unbiased question, no product mention, no links. Reveals
+     what they actually do.
+   - **Reaction** — share the product, force a choice between the option under
+     test and its nearest alternative.
+   One probe or several, whatever fits the goal.
+4. **Scaffold** `docs/validations/<slug>.md` (or wherever you keep validation
+   write-ups): Goal, each probe, a Results table each, empty Verdict. Raw posts go in
+   ``` blocks.
+5. **Write the Verdict** from the pasted replies.
+
+## Rules
+
+- Ask which subreddits the account can post in. Suggest, but don't assume.
+- Don't pad the verdict — if signal is thin or negative, say so.
+- Don't invent replies.
+
+## Post writing style
+
+<!-- Expand with examples of posts that landed and flopped, per subreddit. -->
+
+### Voice
+
+- Write like a quick comment typed in the moment, not edited copy. Casual, no marketing tone,
+  no hype words.
+- Short: a title under ~10 words and 2–4 plain sentences. Long posts read as ads.
+- Title is one plain question. No em-dashes,
+  no slashes, no "X — do you A or B?" headline construction. Just the question.
+- Imperfect on purpose: the odd sentence fragment, drop the wind-up. This is
+  genuine casual voice — NOT faked typos or misspellings. Don't manufacture
+  errors; just stop polishing.
+- First person. State the situation plainly, list the options you're considering
+  if that helps, then ask what they usually do and what they last tried. Avoid
+  invented backstory and dramatic self-talk like "part of me..." or "I'm torn..."
+  because it reads staged. Don't narrate what "some people" do — that reads like
+  a survey.
+- Open straight with the situation or the question. Cut "I've been thinking
+  about…", "curious what people think", and every other warm-up line.
+
+### Background
+
+- Ground it in one concrete situation, not a generic framing. "same complaint
+  keeps coming up from users" beats "when problems arise in your business."
+- Give only enough for someone to answer from experience. Skip the rest — no
+  paragraph of setup, no explaining why you're asking.
+
+### The question
+
+- One specific question answerable from experience ("what's the last one you
+  actually made?") beats a vague "what do you think?".
+- Ask what they *did*, not what they *think*.
+
+### Probe A — unbiased
+
+- No product mention, no links.
+- List the options flat and neutral so you don't lead the answer.
+
+### Probe B — reaction
+
+- One line on what the product does, then the link. Say it's yours — don't hide
+  that you built it.
+- Force a choice between the thing under test and its nearest alternative.
+
+### Gets a post removed
+
+- Self-promo in a no-promo sub, or "I'm doing research" survey framing.
+- Low-karma / new accounts can't post in many subs (AutoModerator checks age and
+  karma before a human sees it) — ask first.
+- Read each sub's rules; they differ. Same post pasted across subs reads as spam.

package/skill/references/propose.md

@@ -0,0 +1,67 @@
+# Propose new tasks
+
+Pick a module, then propose **3 new tasks inside it**. New work, not picks from the
+board — tasks in one focus close a gap; scattered ideas just skim the product.
+
+## 1. Pick the module
+
+**Ask the user to pick one or more modules from the map.** If they leave it open, pick
+one yourself — the one where memory says users stumble most.
+
+Once you have a focus module, its memory set lives at `docs/kanban/memory/<module>/` (keyed
+by its bolded name in `modules.md`) — the four files described in "The memory set" in
+`SKILL.md`. Read that path, not the whole board, so the notes you work from are that
+module's: `readme.md` for what already shipped (links to the published docs),
+`decisions.md` for settled answers you needn't re-open, and
+`redesign.md` / `rejected.md` to avoid wrong designs and re-proposals. For the long-term
+goal, the horizon, and the roadmap, read `docs/kanban/memory/goal.md` — the board root's
+copy is the only one, and it covers the whole project, not this module. While it's
+open, re-judge its `reviewed:` field and fix a stale value by editing that one line
+(the test is under "The memory set" in `SKILL.md`). For a shipped
+behavior's detail, follow `readme.md`'s links into the module's **published docs** — the
+docs are the record, memory only indexes them. A module with no folder yet has no notes.
+With no focus module or no module map, read the project-wide set at `docs/kanban/memory/`
+instead.
+
+**List the cards already tagged with the focus module.** Grep the board for cards whose
+`modules:` field names it — `grep -rl 'modules:.*<module>' docs/kanban/todo/` — and read
+them, so you don't re-propose planned work and you see where the module already has effort.
+
+## 2. Walk it as a user
+
+Ideas come from a walkthrough, not a feature list. Play one real user story in the
+focus, step by step. At each step ask: what can't they see or find? what do they wait
+on, guess at, or redo by hand? Every stumble is a task idea.
+
+Then check the focus's written sources — the code, roadmap doc, user-facing docs
+(Configuration, where shipped behavior is recorded), `todo/`, `rejected.md`, and the focus
+module's memory (from step 1, `readme.md` included) — to catch promised work and stop
+re-proposals.
+
+## 3. Propose 3 tasks
+
+All inside the focus; none already on the board, already shipped (in the published docs or
+`readme.md`), or in `rejected.md` (unsure one is already done? run the Value check in
+`references/refine.md`). Write each
+with the "Add a task" flow in `SKILL.md`.
+
+### Boldness
+
+How big a move each of the 3 is. Whoever asks for the run picks one; **normal** unless
+they say otherwise. It changes the size of the idea, never the count — 3 either way.
+
+- **safe** — polish a rough edge, or fill a gap in something that already works. No new
+  surface: the user's story is the one they play today, just without the stumble.
+- **normal** — a feature each: one card a session can finish. The default size.
+- **bold** — a big leap each: a whole new capability for the module, something the user
+  can't do today at all. Judge it against the long-term goal in
+  `docs/kanban/memory/goal.md`, not against the current rough edges — a bold task is a
+  step toward the horizon. A task this big is normally broad enough to split into
+  subtasks that need splitting again, so write it as a **group task** (see "Group task"
+  in `SKILL.md`); write it as one card only if the split truly doesn't earn its folder.
+
+Boldness is a size, not a licence: a bold task still has to be new (not on the board, not
+shipped, not in `rejected.md`) and still gets written with the "Add a task" flow.
+
+A propose run writes no memory. `readme.md` is the finish flow's record — a scan reads
+it and leaves it alone.

package/skill/references/prune-memory.md

@@ -0,0 +1,29 @@
+# Prune the memory set
+
+Prune every file in the memory set (see "The memory set" in `SKILL.md`). Prune whichever
+copy you're compressing: the project-wide one at `docs/kanban/memory/` or a module's at
+`docs/kanban/memory/<module>/`. `goal.md` is not in the set — it's user-owned, leave it alone.
+
+One principle for all files: they exist to stop us re-proposing work, re-making a
+design mistake, or re-asking a settled question. Rewrite each as **topics** — areas of
+the product — with plain-language takeaways under each. Keep only what helps future
+planning; drop code detail, dates, task ids, step-by-step stories, and the reasoning
+behind settled decisions. Merge lines that say the same thing. Rewrite, don't just cut.
+
+On top of that, per file:
+
+- `rejected.md` — one line per idea: what not to propose and why. "Already done" is a
+  shipped fact, not a rejection — it belongs in the published doc (with a `readme.md`
+  line pointing at it), not here; drop it from `rejected.md`.
+- `redesign.md` — one line per entry: the mistake, then the design to use. Drop an
+  entry once that design is the obvious default.
+- `readme.md` — one line per shipped user-facing behavior. Where a published doc covers
+  it, the line is just a link to that doc's path. **Replace a prose entry with a link
+  only after you have confirmed the doc covers that behavior** — search the docs first;
+  no doc yet means the prose line stays: `readme.md` is the only record until we
+  document it. Anything else — watermarks, a last focus, open gaps, internal detail —
+  doesn't belong here; drop it.
+- `decisions.md` — one line per live decision, in plain user-facing words. Drop anything
+  that fails its bar in SKILL.md ("The memory set"): a call about code detail, or one the
+  published docs now cover. Drop a decision once the question no longer arises or
+  `redesign.md` states it as a rule.

package/skill/references/recurring-task.md

@@ -0,0 +1,93 @@
+# Run a recurring task
+
+A recurring task is a job we repeat on a cadence. Unlike a one-shot task, it never
+archives — each pass is a **run**, and the card gets sharper each run until a run needs
+no human. This guide covers running one and improving it.
+
+## The card shape
+
+A recurring card lives in `todo/recurring/`, its own folder parallel to `blockers/` and
+the track folders (see your tracks in Configuration). Its frontmatter marks the track:
+
+```
+---
+title: …
+track: recurring
+priority: …
+roi: …
+blocked_by: []
+related: []
+questions: []
+---
+```
+
+It adds two sections beyond a normal card:
+
+- `## Process` — the in-order steps of one run, each tagged by how it runs today.
+- `## Runs` — a pointer to the per-run open-questions files.
+
+### The `## Process` ladder
+
+Every step carries one tag:
+
+- `[script]` — a command anyone can run as-is. The most automatic; include the exact
+  command.
+- `[agent]` — a plain-language instruction the agent follows without asking the user.
+- `[ask]` — a step that still needs the user (a judgement call, an approval, missing
+  data).
+
+The whole point of the recurring type is to **move steps up the ladder** over runs:
+`[ask]` → `[agent]` → `[script]`. A run where every step is `[script]` or `[agent]` needs
+no human. Keep the tags honest — only mark a step `[script]` once the command actually
+exists and works.
+
+## One run, start to finish
+
+1. **Read the card**, especially `## Process` and the newest run file under `runs/`.
+2. **Do the steps in order**, following each tag. A `[script]` step: run its command. An
+   `[agent]` step: do it yourself. An `[ask]` step: ask the user, and hold the answer for
+   step 5.
+3. **Record the run:**
+
+   ```
+   ${KB} run <id>
+   ```
+
+   This adds +1 to `completed` in `metrics.csv` and **keeps the card** — no archive, no
+   README edit. It refuses if the card isn't under `todo/recurring/`.
+4. **Self-improve `## Process`.** Rewrite it so the next run needs less human effort:
+   - An `[ask]` you answered the same way it could be derived → rewrite as an `[agent]`
+     instruction.
+   - An `[agent]` step you did the same mechanical way every run → write a small script
+     and change it to `[script]` with the command.
+   - A step that broke or was ambiguous → tighten the wording.
+   Do the smallest real improvement each run; don't invent automation you didn't just do.
+5. **Log what still needed a human.** For each `[ask]` this run, write the question and
+   the user's answer to:
+
+   ```
+   docs/kanban/todo/recurring/<id>-<slug>/runs/<YYYY-MM-DD>-open-questions.md
+   ```
+
+   (Create the `<id>-<slug>/runs/` folder next to the card if it doesn't exist.) Before
+   the next run, fold answered questions back into `## Process` and delete them from the
+   run file. A run file that empties out is the signal that step is now automatic.
+
+## Open-questions file shape
+
+Keep it plain — the question, the answer, and whether it can be automated next time:
+
+```markdown
+# 49 — run 2026-07-10 open questions
+
+- **Which topic this run?** → "cold email reply rates" (user picked).
+  Next: could a script rank sources by pain count and propose the top one? → move to [agent].
+- **Byline author?** → Jane. Stable across runs → fold into Process as a default.
+```
+
+## What not to do
+
+- Don't archive a recurring task or record it as shipped behavior. It has no end state.
+- Don't mark a step `[script]` before the script exists.
+- Don't let run files pile up unread — their whole value is being folded back into
+  `## Process` and then emptied.

package/skill/references/refine.md

@@ -0,0 +1,69 @@
+# Refine
+
+Take one task one step forward — from vague to concrete. First **check** the card, then
+**rewrite it or raise a question**. **Gate:** a card whose `questions` frontmatter isn't
+empty can't be refined — resolve them first (`references/resolve.md`).
+
+## 1. Check
+
+Each line below is one plain question. Answer yes or no; a no needs one line saying
+what's wrong. Flag real problems, not hypotheticals.
+
+- **Format — is it written like a card?**
+  - **On topic**: does the body do what the title says? Anything else is another task.
+  - **Plain language**: is every line plain and short ("Writing style" in `SKILL.md`)?
+  - **No meta**: free of planning notes and meta-todos ("Card format" in `SKILL.md`)?
+  - **A build plan**: is it split into `## Todo` boxes, one step of real work each?
+- **Value — should this task exist at all?**
+  - **Direction**: does it move the project toward the long-term goal and roadmap in
+    `docs/kanban/memory/goal.md`? Suggest rejection in `questions` on a task that's off-goal.
+  - **Already shipped**: is it built already? Code → search the codebase; content → search
+    where that content lives (your reference docs); research → check past write-ups.
+  - **Duplicate**: does another card already own the idea? Then update it, not this one.
+- **Scope — is the plan the right size for the goal?**
+  - **Goal fit**: would the goal still be met with this piece cut? Then it's scope creep.
+    The goal is the title and its "so the user can ..." line, not what the summary grew
+    into; on topic doesn't mean needed. Common drift: the goal is "find a run's log", the
+    plan builds "a history of all runs".
+  - **Missing updates/verification**: does the plan skip work it implies — tests, a review pass, landing
+    copy? If a user can see the change, it carries doc-update todos so it isn't hidden
+    after it ships (`references/document-feature.md`); none needs a why.
+  - **Over-complication**: is the design more machinery than the value justifies?
+  - **Grouping**: does this card only make sense with another one? Then they're one group.
+- **Design — will the plan work?**
+  - **Actionable**: could someone start on it tomorrow, or is it still a rough idea? If
+    the how isn't obvious, are the options laid out with one recommended?
+  - **Unambiguous**: can it be built without guessing? Code detail isn't needed; an open
+    requirement is.
+  - **Full user flow**: does the design cover the full user flow, not just the piece the title
+    names? For example, auth isn't just login — sign-up and log-out too.
+  - **Edge cases**: does the design hold up on them? Re-check the decisions the card
+    states — written doesn't mean right. E.g. tasks kept in memory are lost on restart.
+- **Status — does the card match what's already built?**
+  - **Stale todos**: is each unchecked todo really still undone? Work lands without the
+    box getting ticked.
+  - **Finished**: are all the todos done **and** the goal met? Then it's not refinable.
+
+## 2. Rewrite, or raise a question
+
+Every NO turns into exactly one move below; a card with no problems skips them.
+**Never write the review notes into the card** The card holds the plan and nothing else.
+Read the "Card format" and "Writing style" of `SKILL.md`.
+
+- **Rewrite.** Fix the issues while maintaining a minimal task spec.
+- **Reject.** A failed Value check. "Reject an idea" in `SKILL.md`: a line in
+  `rejected.md`, then `${KB} reject <id>`. Unsure the value is real? Raise a question.
+- **Add a card.** A side idea, an unplanned, separate concern that doesn't
+  belong to this card. "Add a task" in `SKILL.md`, minding `references/add-task.md`'s rule
+  against near-duplicate splits.
+- **Group.** Cards that only make sense together: "Group task" in `SKILL.md` and "Tightly
+  coupled tasks go in one group" in `references/add-task.md`.
+- **Archive.** Everything done and the goal met: "Finish a task" in `SKILL.md`.
+- **Raise a question** instead of rewriting when the call is the user's (taste, priorities,
+  money, product direction), or a **spec-level** problem is significant and you can't
+  settle it — is this what the user wants, which of two shapes should the feature take,
+  what's the rule in a case the card never names. Record it with `${KB} update <id>
+  --question ".."` (repeat the flag), leave that part alone; small calls, make them.
+- **Mark it ready.** A concrete plan and no open questions finishes the card: `${KB} update
+  <id> --status ready` — only if this refine stopped at the code level, not one stage
+  short. The user scans for the `ready` pill to pick what to build next.

package/skill/references/resolve.md

@@ -0,0 +1,56 @@
+# Resolve open questions
+
+## Try to answer each question yourself
+
+Research first — the module's code, the board, the memory set of any module the card
+names (`docs/kanban/memory/<module>/`), and your reference docs. Many questions are
+already settled, shipped, or rejected once you look.
+
+Judgment calls — taste, priorities, money, product direction — get the same pass:
+the trail of past `decisions.md`, `rejected.md`, `redesign.md`, and the board root's
+`goal.md` often shows the user already made this call, or one close enough to decide from.
+
+Decide yourself when the evidence gives you confidence. Note the decision and reason
+under `## Decided by the agent` (read "Card format" in `SKILL.md`).
+
+## Ask the user the rest
+
+Ask when the evidence isn't enough. Write the options
+and your recommendation into the question text itself. Keep it plain and short: one
+line the user can answer at a glance.
+
+> Where should the board live? (a) local files — simple; (b) GitHub Projects — syncs
+> with issues. Recommend (a).
+
+Run `${KB} tag <id> 1,2,3 user` for these questions.
+
+## Update the frontmatter
+
+- All answered → `${KB} update <id> --clear-questions`
+- Some answered → `${KB} update <id> --drop-question 1,3` — the 1-based numbers of
+  the answered ones. The rest stay untouched, tags included.
+
+## Fold the answers into the card
+
+Rewrite, don't append. Follow SKILL.md's "Card format" and "Writing style": keep the
+card a minimal task spec. Merge answers on the same topic into one entry — not necessarily one
+entry per question. Cut what the spec no longer needs.
+
+An answer sometimes creates work the `## Todo` list doesn't cover — append it as new
+unchecked todos, even when every box is ticked: an open question meant the card wasn't
+finished, so the answers are the remaining work.
+
+## Record lasting decisions
+
+Append the user's calls to `memory/<module>/decisions.md`, under the topic that fits —
+add a topic, or a subtopic under an existing one, when none does.
+
+- **Only what the user decided.** Agent's own calls stay on the card (read "Card format" in
+  `SKILL.md`). This file is what the human settled.
+- **Skip** implementation-level and non-user-facing calls.
+- **One plain line each**, written as `**<key>**: <call>` — the key is the question the
+  call settles, or a short title for it. Give the call, not the reasoning, but keep it
+  clear to someone planning another card:
+  `**Where does a finished card go?**: to .archive/, kept in git. A rejected card is deleted.`
+- **A new call replaces the old.** Rewrite the line it contradicts, never leave both. If
+  you can't tell which one the user holds, change nothing and ask with a `[user]` question.