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:

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.

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:

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.

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:

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