add-to-roadmap

Files (1)

• SKILL.md

SKILL.md (first lines)

# /add-to-roadmap

Add a new task item to a named phase or section in `ROADMAP.md`.

**Arguments:** `$ARGUMENTS`

Parse `$ARGUMENTS` by splitting on the first occurrence of `::` (space,
double-colon, space). Left side (trimmed) → `<phase-or-section>`. Right side
(trimmed) → `<task-text>`. If `::` is absent, stop immediately with:

> "Malformed arguments: expected `<phase-or-section> :: <task-text>` — the `::`
> separator is missing."

---

## Locating ROADMAP.md

Start at CWD and walk up the directory tree, checking each directory for a file
named exactly `ROADMAP.md`. Stop walking at the git repository root:

```
REPO_ROOT=$(git rev-parse --show-toplevel) || exit 1
```

If `git rev-parse` fails (not a git repository), stop with:

> "Not a git repository. /add-to-roadmap requires a git repo at CWD."

Walking up: check `$CWD/ROADMAP.md`, then `$CWD/../ROADMAP.md`, and so on,
stopping at `$REPO_ROOT` inclusive. If `ROADMAP.md` is not found in any of those
directories, stop with:

> "ROADMAP.md not found anywhere between CWD and the repository root
> (`$REPO_ROOT`). Create one or move to a subdirectory of a repo that has one."

---

## Address-space resolution

### Parsing headers

Scan every line of `ROADMAP.md`. Collect all addressable headers:

- `## Phase N — ...` lines → Phase headers (level 2).
- `### ...` lines → Subsection headers (level 3).

Build an ordered list of `(header_text, start_line)` tuples. `header_text` is
the full text after `## ` or `### ` (without the `#` prefix or trailing
whitespace).

### Fuzzy contains-match

Normalize the operator-supplied `<phase-or-section>` by lowercasing it. For each
header in the collected list, lowercase `header_text` and check whether the
normalized input is a substring of the normalized header text. This match is
case-insensitive.

Example: input `"phase 2"` matches `## Phase 2 — Skill hardening` because
`"phase 2"` is contained in `"phase 2 — skill hardening"`.

Example: input `"measurement"` matches `### Measurement & perception` because
`"measurement"` is contained in `"measurement & perception"`.

### Match outcomes

**Zero matches:** Stop with:

> "No headers matched `<phase-or-section>`. Available headers:
> `<bulleted list of all header_text values>`."

**Multiple matches (disambiguation):** Stop with:

> "Ambiguous: `<phase-or-section>` matched more than one header. Please narrow
> the input:
>
> - `<header_text_1>` (line N)
> - `<header_text_2>` (line N) ..."

List every matching header so the operator can refine the input.

**Exactly one match:** Proceed to insertion.

### Nested-section name collision precedence

A Phase-2 header might contain the same substring as one of its child Subsection
headers — for example, if a Phase is named
`## Phase 5 — Skill catalog expansion` and a subsection under it is
`### Skill-testing & operator-mode skills`, then the input `"skill"` matches
both. This is treated as an **ambiguous match** (multiple matches) regardless of
nesting depth — there is no automatic promotion of Phase headers over Subsection
headers or vice versa. The operator must supply a more specific input to resolve
it.

---

## Item formatting

### Schema (from ROADMAP.md)

New items follow the checkbox format observed in the existing roadmap:

```
- [ ] **<bold-name>** — <description>
```

The separator between the bold name and description is an **em dash** (`—`), not
a hyphen or en dash. A single space precedes and follows the em dash.

### Deriving `<bold-name>` and `<description>`

Split `<task-text>` on the first `—` (space, em dash, space) if present:

- Left side → `<bold-name>` (strip backtick-wrapped skill names if relevant).
- Right side → `<description>`.

If no em dash is found in `<task-text>`, use the entire text as `<bold-name>`
and leave `<description>` empty, yielding `- [ ] **<task-text>**`.

### Multi-line wrap

From laurac8r/claude-damn, MIT.

More from laurac8r/claude-damn