kb-roadmap
/kb-roadmap
Uzgadnia plany z faktycznym dostarczaniem: wczytuje źródła planu (zgłoszenia, kamienie milowe, OKR) i dostarczenia (git, ADR, release log), wykrywa rozbieżności i tworzy żywą mapę drogową w Markdown, HTML i JSON.
- Autor
- wlfghdr ↗
- Repozytorium
- agentic-kb ↗
- Licencja
- Apache-2.0
- Ostatnia zmiana repozytorium
- 14.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 21
- Skrypty
- 1
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 1
Brak sygnałów. Repozytorium zmienione 14.10.2026, bez odwołań do wycofanych modeli i API.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
- 1 skrypt w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.
Skrypty: scripts/kb_roadmap.py
Co robi i kiedy
Uzgadnia plany z faktycznym dostarczaniem: wczytuje źródła planu (zgłoszenia, kamienie milowe, OKR) i dostarczenia (git, ADR, release log), wykrywa rozbieżności i tworzy żywą mapę drogową w Markdown, HTML i JSON.
Oryginalny opis (EN)
Reconcile planning-truth sources against delivery reality. Ingests ≥1 plan source (ticket export, milestone markdown, OKRs) and ≥1 delivery source (git repository, ADR set, release log), runs a five-tier correlation ladder, detects mismatches, and emits a living roadmap artifact in Markdown, HTML, and JSON. Triggered by `/kb roadmap` and roadmap-reconciliation phrases.
Jak działa
- When to invoke
- The single command model
- Core rules (always apply)
- The correlation ladder
- Directory contract (adopter's KB)
- Two views
- Roadmap communication contract
- Configuration contract
- Artifact sections (MD and HTML mirror each other)
- Output contract
Podgląd SKILL.md
---
name: kb-roadmap
description: Reconcile planning-truth sources against delivery reality. Ingests ≥1 plan source (ticket export, milestone markdown, OKRs) and ≥1 delivery source (git repository, ADR set, release log), runs a five-tier correlation ladder, detects mismatches, and emits a living roadmap artifact in Markdown, HTML, and JSON. Triggered by `/kb roadmap` and roadmap-reconciliation phrases.
triggers:
- "/kb roadmap"
- "roadmap synthesis"
- "product roadmap"
- "phase roadmap"
- "now next later"
- "roadmap presentation"
- "customer-value roadmap"
- "plan vs delivery"
- "plan delivery reconciliation"
- "deviation digest"
- "roadmap digest"
tools: []
requires:
- kb-management
author: agentic-kb contributors
homepage: https://github.com/wlfghdr/agentic-kb
license: Apache-2.0
---
# Skill: KB Roadmap
Organizations always have **at least two sources of planning truth** — tickets and the repository, milestones and delivery, OKRs and commits. They drift. Manual reconciliation is expensive and always stale. This skill closes the loop: it ingests plan + delivery, correlates them across a five-tier ladder, and produces a roadmap artifact that says what is planned, what is delivered, and where the two disagree.
This skill is **vendor-neutral**. All vocabulary specific to a particular tracker, repository host, or organization lives in the adopter's `.kb-config/layers.yaml` and `.kb-config/artifacts.yaml`, never in this skill.
The roadmap is a **product-management artifact**, not just a tracker report. Its job is to make planned customer/user value, confidence, delivery reality, and source traceability visible in one place.
The skill resolves its `roadmap:` block from the **active layer** entry in `.kb-config/layers.yaml` and can normalize read-only tracker inputs from that layer's `connections.trackers[]` declarations when legacy `roadmap.issue-trackers[]` entries are absent.
## When to invoke
Invoke whenever the user:
- Types `/kb roadmap` (optionally followed by `--since`, `--scope`, `--workstream`, `digest`, `sync`).
- Asks for a roadmap, status, or deviation report that spans both a planning tool and a repository.
- Asks *"what shipped vs. what was planned?"*, *"where does my roadmap drift from reality?"*, or *"which tickets have no code?"*
## The single command model
One entry point — `/kb roadmap` — with context-driven subcommands:
| Input | Action |
|---|---|
| `/kb roadmap` | Generate artifact with default scope + timeframe |
| `/kb roadmap --since YYYY-MM-DD` | Custom baseline |
| `/kb roadmap --scope <name>` | Scope to a workstream declared in `.kb-config/layers.yaml` |
| `/kb roadmap digest` | Pull latest plan + delivery state; compute delta; do not render |
| `/kb roadmap sync` | Propose plan-source updates based on delivery reality (dry-run default) |
Full reference: `references/command-reference.md`.
Concurrency contract: [`docs/concurrency.md`](../../../../docs/concurrency.md) governs shared-layer promote collisions, diverged backlinks, topic merges, and append-only logs. Roadmap flows that read or write shared KB artifacts must honor the same `/kb sync` and `/kb audit` reconciliation rules.
## Core rules (always apply)
1. **Every run writes three artifacts** — Markdown, HTML, JSON — with the same base name and timestamp. The JSON is authoritative; MD + HTML render from it.
2. **Correlation ladder has five tiers.** Stop at the first match; classify every matched pair by tier. Unmatched items on both sides become mismatch findings.
3. **Never silently drop an unmatched item.** It is either a delivery-without-plan, a plan-without-delivery, or a traceability gap — all three are first-class artifact entries.
4. **Deep-investigation matches (tier 4) are proposed, never final.** Emit them as `proposed, pending review`; the user confirms before downgrading to tier 1–3.
5. **Graceful degradation.** Artifact must be useful even when correlation rate is 0% — in that case, plan + delivery render side-by-side with an explicit "no matches found" banner.
6. **Read-only by default.** `digest` and plain `roadmap` never write to plan sources. `sync` emits a dry-run plan unless `--apply` is passed. A tracker mutation—including a mismatch `link`—may proceed only when `primitive-storage.roadmap-items` selects that tracker, the matching `connections.trackers[]` entry declares the canonical operation, authentication/tooling is available through canonical `auth-env` or the adapter's documented ambient authentication, and the user confirms that one write. Failed ownership follows the configured canonical home without offering a noncanonical tracker mutation; a mismatch against another read source remains a manual mapping. Legacy `roadmap.issue-trackers[].write-*` names are migration input, not mutation authority. See `references/issue-trackers.md`.
7. **Resume routing is deterministic.** When invoked with no work to do, run the conformance check + state assessment + ordered resume rules from `references/state-machine.md`. LLM judgment is not used to pick the next action.
8. **`/discuss` mode is write-free.** When the user message contains `/discuss`, do not regenerate artifacts, apply tuning, or write to trackers. Explain, propose, preview — see `references/discuss-mode.md`.
9. **Continuous config tuning is opt-in.** After each run, emit a tuning digest (zero-match filters, low-match filters, unreachable items, suspected noise). Apply only via `/kb roadmap tune` with explicit per-proposal confirmation. See `references/issue-trackers.md`.
10. **Log every run** to the adopter's `.kb-log/YYYY-MM-DD.log`.
11. **Zero vendor strings in skill code.** Tracker adapters, ticket-key patterns, phase names, status mappings, correlation rules, and styling all come from config.
12. **Journeys are ground truth when declared.** If the scope has `journey-refs`, every **non-infrastructural / non-foundational** item is cross-checked against its cited journey step(s): items with broken citations, uncovered steps, and reality-vs-readiness drift all surface as first-class findings. Infrastructure, build, security-hardening, platform, and foundational work satisfy the rule via an explicit escape hatch (label, trailer, or ADR link — see `references/audit.md` R1). Authoring commands (`ideate`/`discuss`/`review`/`refine`) treat the journey as the third party in every critique. The journey is never silently updated by roadmap runs — drift findings offer a transition into `/kb journeys review` instead. See `references/journey-grounding.md`.
13. **The audit is the consistency gate.** `/kb roadmap audit` runs all 15 rules (mappings · timeline · scope · structural) and emits a triple-artifact report with an actionable correction per violation. It is the single sanctioned path to reconcile gaps across issues ↔ roadmap items ↔ journey steps. See `references/audit.md`.
14. **No roadmap artifact without timeline + status board.** The HTML must always include a quarter-axis timeline (section 02) and a phase-columned kanban status board (section 03), in that order. When data is thin, both sections degrade gracefully (empty quarters, empty columns) — they never disappear. See `references/html-template.md` for the full template contract.
15. **Presentation roadmap view is value-first.** When rendering a phase/lane roadmap for humans, aggregate noisy source inputs into lanes and phases, keep each lane to a small number of items per phase, and phrase each item as a customer/user value headline plus a second-line implementation detail. Do not use checkmarks for proposed work; checkmarks mean implemented or already true.
16. **Commitment status is explicit.** Roadmap items distinguish `draft`, `proposed`, `agreed`, `committed`, `in-delivery`, and `shipped` (or the adopter's mapped equivalents). The rendered artifact must make the confidence/commitment level visible so a draft alignment board is not mistaken for an approved plan.
## The correlation ladder
Apply in order. Stop at the first tier that matches. See `references/correlation-ladder.md` for details.
| Tier | Signal | Example |
|------|--------|---------|
| 1 | Direct key match | Ticket key in commit message, PR title, branch name, or PR body |
| 2 | Cross-reference graph | Ticket remote-links point at PR; PR body references ticket; git trailer asserts ticket |
| 3 | Temporal + textual heuristic | Ticket status change and commits overlap in time window, by same author, with title-token overlap above threshold |
| 4 | Deep investigation (LLM-assisted) | For still-unmatched items on both sides, produce a ranked candidate-match list with rationale; flag `proposed, pending review` |
| 5 | Mismatch finding | Remaining unmatched items classified into `delivered-unplanned`, `planned-undelivered`, `traceability-gap` |
## Directory contract (adopter's KB)
The skill writes into a **dedicated** `_kb-roadmaps/` folder at the adopter's KB root — a peer of `_kb-references/`, `_kb-decisions/`, `_kb-ideas/`, `_kb-tasks/`, not a subdirectory of reports. Roadmaps are a distinct primitive.
```
my-kb/
├── .kb-config/
│ ├── layers.yaml # active layer declares roadmap: and optional connections:
│ └── artifacts.yaml # declares html-template + brand assets
├── _kb-roadmaps/ # dedicated root (configurable via roadmap.output-dir)
│ ├── <workstream>/ # per-workstream detail view
│ │ ├── roadmap-YYYY-MM-DD.{md,html,json}
│ │ └── status-YYYY-MM-DD.{md,html,json}
│ ├── exec/ # cross-workstream roll-up (C-level)
│ │ └── roadmap-exec-YYYY-MM-DD.{md,html,json}
│ ├── index.html # auto-generated; links to latest per scope
│ └── archive/ # older than retention-days
├── _kb-references/findings/ # mismatch findings land here (opt-in)
└── .kb-log/YYYY-MM-DD.log
```
## Two views
**Detail view** (per workstream): full sections A–G — ticket + commit detail, correlation audit, local scope refinement, and the bottom-up evidence trail from daily work. Audience: the team driving the workstream and whoever owns the domain outcome.
**Roll-up view** (exec / C-level): sections X1–X7 — portfolio state, momentum, risks, shifts, scope changes, decisions needed, next-period focus. No commit-level detail. Audience: leadership and the lead curating the joint roadmap.
Declare scopes in the active layer's `.kb-config/layers.yaml` entry under `roadmap.scopes`. Default: every workstream gets a detail scope; adopters add one `kind: roll-up` scope per leadership rhythm.
See `references/folder-layout.md` for the full contract.
## Roadmap communication contract
When `/kb roadmap` renders a presentation-oriented roadmap view, it applies these generic communication rules:
| Rule | Contract |
|------|----------|
| Phase clarity | Use adopter-configured phases, but provide a concise legend that separates past truth, active work, proposed scope, later follow-up, and strategic direction. |
| Lane aggregation | Group source items into a small set of product or workstream lanes. Dense ticket lists stay in the appendix / JSON, not in the board. |
| Value headline | The first line answers: what does a user, customer, operator, or stakeholder get that they did not get before? |
| Detail line | The second line explains what/how: tracker cluster, implementation mechanism, dependency, or source basis. |
| Draft callout | If the run is synthesis-only, mark the artifact as draft / not agreed and name what would make it agreed. |
| Implemented marker | Use checkmarks only for implemented or already-true capabilities verified by delivery sources or accepted docs. |
| Traceability | Every visible roadmap item keeps source refs in JSON and appendix even when the board text is deliberately short. |
The default phase labels are generic and may be renamed in config: `done`, `now`, `next`, `later`, `future`. The renderer may expose a `now / next / later` presentation mode, but the JSON sidecar keeps the canonical phase and commitment fields.
## Configuration contract
See `references/config-schema.md`. Minimum adopter config in the active layer entry of `.kb-config/layers.yaml`:
```yaml
layers:
- name: alice-personal
path: .
connections:
trackers:
- name: jira-export
kind: jira
export-dir: ../exports/jira
roadmap:
default-scope: <workstream-name>
default-timeframe: week # week | month | quarter | since:DATE | range:A..B
output-dir: _kb-roadmaps
scopes:
<workstream-name>:
kind: detail
correlation:
ticket-key-pattern: "[A-Z]+-\\d+"
branch-prefixes: [feature/, fix/, chore/]
trailer-keys: [Ticket, Issue, Jira]
deep-investigation: true
mismatch-findings:
route-to: _kb-references/findings
min-loc-threshold: 20
stalled-after-days: 14
```
Brand + styling live in `.kb-config/artifacts.yaml`:
```yaml
html-template:
base: kb-roadmap/templates/roadmap.html
tokens: neutral # or a path to a tokens file
logo: # optional SVG in header, respects theme
light: ""
dark: ""
themes: [light, dark, auto]
```
## Artifact sections (MD and HTML mirror each other)
All sections are **mandatory**. Empty sections render with an explicit "no items" note.
| Section | Content |
|---------|---------|
| **A. Plan baseline** | All plan items in scope, grouped by the configured `hierarchy` |
| **B. Delivery baseline** | All delivery signals in scope (commits, PRs, tags, ADRs) |
| **C. Correlation matrix** | Matched pairs grouped by ladder tier; counts per tier |
| **D. Delta since baseline** | Items newly opened, changed, merged, or shipped since `--since` |
| **E. Mismatch findings** | `delivered-unplanned` · `planned-undelivered` · `traceability-gap` · `journey-uncovered` · `journey-citation-broken` · `journey-reality-mismatch` |
| **F. Forward plan** | Plan items in status `next`/`in-progress`, kanban view, plus highest-impact uncovered journey steps as candidate-next-work |
| **G. Decisions needed** | Cross-reference to `_kb-decisions/` + suggested new decisions from gaps, including journey-drift decisions |
## Output contract
Every response:
1. **What I did** — one short statement.
2. **Where it went** — paths to the three emitted artifacts.
3. **Correlation summary** — items matched per tier + mismatch counts.
4. **Suggested next steps** — 1–3 concrete follow-ups (confirm tier-4 matches, open decisions for gaps, adjust plan-source).
## Safety rules
- **Never push to plan sources without explicit `--apply`.** Even then, require confirmation.
- **Never include raw credentials or tokens** in artifact output — scrub before render.
- **Never fetch external URLs** beyond declared source paths without informing the user.
- **Never block on missing data** — degrade and surface the gap in the artifact itself.
## Adapter contract
Source adapters are declared by name in config. The skill ships with a minimum neutral set; adopters add more by dropping a Python module under `scripts/adapters/` that exports a `load(config) -> list[Item]` function.
Shipped adapters:
| Name | Kind | Reads |
|------|------|-------|
| `ticket-export-markdown` | plan | a directory of markdown files with YAML frontmatter (Program/Package/Item hierarchy) |
| `milestone-markdown` | plan | `*.md` files with a `## Milestones` heading |
| `git-repo` | delivery | a git checkout — commits, PRs via GitHub CLI, tags, ADR glob |
| `release-log` | delivery | a `CHANGELOG.md` or `RELEASES.md` |
See `references/adapters.md`.
## References (load on demand)
- `references/correlation-ladder.md` — the five tiers, in depth
- `references/adapters.md` — source adapter contract and shipped set
- `references/issue-trackers.md` — **bidirectional tracker model** (read + write + continuous tuning)
- `references/phase-gates.md` — generic phase pipeline for plan items (`idea` → `defined` → `committed` → `in-delivery` → `shipped`)
- `references/state-machine.md` — inline state markers + deterministic resume routing
- `references/discuss-mode.md` — `/discuss` contract (no writes, propose-only)
- `references/authoring-commands.md` — `ideate` (creative), `discuss` (devil's advocate), `review` (challenge + create), `refine` (implementation plan)
- `references/mismatch-findings.md` — classification rules, noise filters, routing
- `references/journey-grounding.md` — journeys as reference + review lens + consistency check for every roadmap run
- `references/audit.md` — `/kb roadmap audit`: 15 rules across mappings / timeline / scope / structural, with offered corrections
- `references/html-template.md` — generated HTML contract: required sections (timeline + kanban are mandatory), derivation rules, adopter customization points
- `references/config-schema.md` — full `.kb-config/layers.yaml` `roadmap:` block
- `references/artifact-contract.md` — MD/HTML/JSON output specs
- `references/folder-layout.md` — `_kb-roadmaps/` layout + detail/roll-up views
- `references/command-reference.md` — full subcommand details
## Templates
- `templates/roadmap.md.hbs` — markdown report template
- `templates/roadmap.html.hbs` — HTML report template (neutral palette, dark/light toggle, optional logo slot, WCAG AA, print fallback)
- `templates/roadmap.json.schema.json` — JSON sidecar schema
## Status
Stable setup-proposed skill (`v2.0.0`). It is offered when the user's role, goals, sources, or desired outputs imply product-management roadmap work; adopters confirm the owning layer by declaring a `roadmap:` block on that layer in `.kb-config/layers.yaml`.
The shipped helper script covers config-driven generation and dry-run validation for detail and roll-up scopes. Apply-capable flows such as `sync`, `tune`, `review-tier-4`, and plan-source writes stay behind explicit command and confirmation gates defined in the behavioral contract above.
Pliki w paczce (21)
- README.md 3 KB
- SKILL.md 18 KB
- references/adapters.md 6 KB
- references/artifact-contract.md 4 KB
- references/audit.md 7 KB
- references/authoring-commands.md 12 KB
- references/command-reference.md 8 KB
- references/config-schema.md 10 KB
- references/correlation-ladder.md 4 KB
- references/discuss-mode.md 2 KB
- references/folder-layout.md 3 KB
- references/html-template.md 8 KB
- references/issue-trackers.md 10 KB
- references/journey-grounding.md 7 KB
- references/mismatch-findings.md 3 KB
- references/phase-gates.md 3 KB
- references/state-machine.md 4 KB
- scripts/kb_roadmap.py 96 KB
- templates/roadmap.html.hbs 11 KB
- templates/roadmap.json.schema.json 4 KB
- templates/roadmap.md.hbs 3 KB
Wersje
W bazie nie ma innych skilli o nazwie kb-roadmap.
Migawka bazy z 13.11.2026 · wersja paczki bc3c11dbada4 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 92review-roadmap
Przegląda mapę drogową w nowym agencie przed jej zablokowaniem, uruchamiany poleceniem /review-roadmap. - 100issues-and-roadmap
Planuje pracę w repozytorium GitHub, czyli kamienie milowe, mapę drogową i zgłoszenia gotowe dla nowych współtwórców. - 100product-roadmap
Układa roadmapę produktu na wyraźne żądanie: kamienie milowe wyników, zakres MVP, cele wyłączone, ryzyka i bramki dowodowe. - 100product-roadmap
Układa roadmapę produktu na wyraźne żądanie: kamienie milowe wyników, zakres MVP, cele wyłączone, ryzyka i bramki dowodowe. - 82review-roadmap
Ocenia mapę drogową w świeżej sesji agenta przed jej zamknięciem, żeby wychwycić luki i sprzeczności w planie prac. - 96sync-roadmap
Porównuje stan pozycji w ROADMAP.md z obecnością plików SUMMARY.md i koryguje rozbieżności.