| name | roadmap-capture |
| description | Use when a user says a feature, bug fix, experiment, or follow-up can wait, should be done later, belongs on the roadmap/backlog, or asks to add/update roadmap items. Two tracks — user-visible product changes go to docs/Roadmap.md (CI-synced to GitHub Issue |
Skill: Roadmap Capture
Instructions
Use this skill when a development discussion produces deferred work such as
"나중에 하자", "추후", "로드맵에 넣자", "backlog", or "TODO로 남기자".
Step 0 — route to a track
| Track | File | Carries | Reflection |
|---|
| 1 | docs/Roadmap.md (+ docs/roadmap/ refs) | User-visible product features/changes | CI-synced to GitHub Issue #7 + gh-pages notice (public text) |
| 2 | AGENTS-ROADMAP.md (repo root) | Dev-internal: tooling, build/CI, refactors, tech debt, agent workflow | None — internal only, no CI |
Routing rule: would a user read this item in the public roadmap/notice?
Yes → Track 1. Only developers/agents care → Track 2. If genuinely unclear,
ask the user which track.
Track 1 — docs/Roadmap.md (user-facing, CI-coupled)
- Capture the deferred item in plain user-facing wording.
- If the user did not specify priority, ask for one priority before editing:
P0 stability/operation, P1 execution/notification/update, P2
user-facing expansion, or P3 long-term review.
- Update
docs/Roadmap.md; it is the single source of truth for this track.
- Add the item under the selected priority as a checklist entry.
- If the item needs more than one sentence of detail, create or update
docs/roadmap/<kebab-case-topic>.md and append
([ref](roadmap/<kebab-case-topic>.md)) to the checklist item.
- For completed roadmap work, move the checked item to the
완료됨 section
instead of leaving it in its old priority bucket.
How Track 1 reflection works (why wording is gated): on a master push
touching docs/Roadmap.md / docs/roadmap/**,
.github/workflows/sync-roadmap-issue.yml rebuilds the GitHub Issue #7 body
via scripts/build-roadmap-issue-body.cjs (ref links stripped), and
sync-roadmap-notice.yml regenerates the gh-pages notice/[notice]roadmap.md
via scripts/build-roadmap-notice.cjs, which the launcher surfaces to users.
Both outputs are public, so:
- Get the user's confirmation of item wording (and priority) before the
change can reach master.
- Never manually edit GitHub Issue #7 — the sync workflow overwrites it
(ref links are stripped automatically).
- Never manually edit the
gh-pages notice files — the notice workflow
rebuilds them.
- The paths
docs/Roadmap.md / docs/roadmap/** are hardcoded in CI and
scripts — do not move or rename them (see docs/README.md).
Validation after editing Track 1 content:
npm run roadmap:issue-body
npm run roadmap:notice
In this Windows-first repo, run npm scripts from Windows PowerShell as
described in AGENTS.md.
Track 2 — AGENTS-ROADMAP.md (agent-internal, no CI)
Format mirrors project_tui's root ROADMAP.md: checkbox milestones with
optional DoD / verification / priority. Append-friendly; no CI coupling, no
public exposure, hence no wording gate.
- Append a checkbox entry
- [ ] <item> to the backlog section (create a
new section only when a grouping is obvious).
- When known, add one indented line:
— DoD: <observable pass condition> / 검증: <how + env tag [WSL | Windows-pwsh | 사용자]>. Add a priority
prefix (e.g. (P3)) only if the user gives one — do not invent it.
- Link supporting docs inline (
docs/archive/..., docs/work/...);
docs/roadmap/ ref docs belong to Track 1 only.
- Completed items: check the box; move to a
완료 section when the list
gets noisy.
- No validation scripts apply — nothing is generated from this file.
Examples
- User: "자동화 실패 판정은 나중에 하자" → user-visible behavior → Track 1.
Ask for priority if missing; add a checklist item; create a detail ref
only if the discussion includes enough policy or design detail to preserve.
- User: "이건 P1로 로드맵에 넣어" → Track 1, add directly under
## P1 - 실행, 알림, 업데이트.
- User: "husky가 WSL에서 깨지는 건 나중에 고치자" → dev tooling → Track 2
(
AGENTS-ROADMAP.md), checkbox + one DoD/검증 line.
- A review finds an out-of-scope refactor/tech-debt item → Track 2, no
wording gate — keep the entry short and factual.
