kb-roadmap

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.
version	1.0.0
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 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, and --apply requires a confirmation prompt. Tracker writes (comments, status, links) require the same --apply gate.
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:

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:

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 (v1.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.

Changelog

Date	What changed	Source
2026-05-24	Added a concurrency-contract pointer so roadmap adopters can find the shared-layer /kb sync and /kb audit reconciliation rules from the skill spec. Closes #124	/kb sync contract reconciliation
2026-05-15	Promoted the roadmap skill contract to stable v1.0.0, removed draft-status frontmatter, and clarified that apply-capable flows are stable but gated by explicit commands and confirmations	Release-readiness audit
2026-05-08	Bumped to v0.2.0 and clarified the current helper-script adapter/runtime coverage against the broader draft command surface	Integration pass
2026-04-30	Promoted roadmap work into the product-management surface: added value-first presentation rules, draft/agreed/shipped commitment visibility, setup-proposed status, and broader natural-language triggers	Product-management surface integration
2026-04-25	Aligned the draft roadmap contract with the shipped 5.1 behavior: the active layer owns the roadmap: block, connections.trackers[] can seed read-only tracker inputs, and the examples no longer imply the retired top-level shape	v5.1.0 closeout release