| name | overview |
| description | SpecKit overview-canvas skill for OpenELIS. Generates an interactive HTML dashboard from a feature's spec.md / plan.md / research.md / tasks.md that surfaces user stories, milestones, data model, decisions, API, and AC coverage in 2-level progressive disclosure (tabs → expandable cards). Light + dark mode + inline markdown rendering of spec files. Auto-deployed via GitHub Pages when the spec dir is on the main branch. Use after `/speckit.tasks` is complete, when a stakeholder-friendly view of dense spec artifacts is wanted, or when sharing a feature for non-engineering review. |
/speckit.overview Skill
Use this skill when:
- a feature's SpecKit artifacts (
spec.md + plan.md + research.md + tasks.md + optional data-model.md + contracts/) are complete and you want a stakeholder-friendly interactive canvas of the content
- preparing a spec PR for non-engineering review (designers, QA, product, lab admins) — the canvas surfaces the structure without forcing readers through 200KB of dense markdown
- demoing a feature's design to stakeholders external to the engineering team
- maintaining a "single pane of glass" overview that drills down into the underlying spec files
- onboarding a new engineer onto a feature — the canvas's Overview tab gives them the executive summary; the Spec Files tab lets them drill into any file's markdown rendered with proper headings, code blocks, tables
Primary Entrypoint
/speckit.overview <SPEC_DIR> — reads the spec markdown files, extracts canvas data into canvas-data.json, assembles canvas/overview.html from the template, and prints the deployed-on-merge URL.
If <SPEC_DIR> is omitted, the skill auto-detects from git branch --show-current (e.g., feat/ogc-285-spec-cleanup → specs/OGC-285-barcode-label-presets/).
Lifecycle
- Detect / accept spec dir —
specs/<feature>/.
- Extract —
scripts/extract-spec-data.py <SPEC_DIR> reads spec.md / plan.md / research.md / tasks.md and writes <SPEC_DIR>/canvas/canvas-data.json.
- Build —
scripts/build-canvas.py <SPEC_DIR> substitutes the JSON into templates/canvas.html.template and writes <SPEC_DIR>/canvas/overview.html.
- Verify — open the file locally to confirm rendering; the GitHub Pages workflow auto-deploys on push to main.
- Surface URL — print the deployed URL (
https://digi-uw.github.io/OpenELIS-Global-2/specs/<feature>/canvas/overview.html) so it can be attached to PR / Jira.
Core Non-Negotiables
- 2-level progressive disclosure only (tabs → expandable cards). No deeper nesting. See reference/canvas-ux-research.md for the Nielsen Norman Group guidance behind this.
- 5–7 KPI cards on the Overview tab (cognitive comfort zone per B2B Dashboard IA 2026 research).
- Strong information scent — every tab has a count badge; every expandable card has a status chip before expanding.
- Light + dark mode — default = system
prefers-color-scheme; user choice persists to localStorage.
- Spec Files tab renders markdown inline via
marked + DOMPurify CDN — readers don't have to leave the canvas to read the source.
- Standardized data shape — see reference/data-extraction.md for the JSON schema.
- No personal-references content — the canvas should reflect what the spec contains, not litigate retrospectives. If the spec is professional, the canvas is professional.
Execution Invariants
- Canvas output ALWAYS goes to
<SPEC_DIR>/canvas/overview.html. The canvas/ subdir is a convention; do not move files to spec-dir root.
- The HTML is a single self-contained file (Tailwind CDN + esm.sh + Babel Standalone + lucide-react + marked). No build step beyond the Python assembly. Opens directly in a browser.
- The Python scripts have ZERO external dependencies beyond Python 3.9+. Pure stdlib (regex parsing of markdown).
- When the spec dir doesn't have one of the optional files (e.g.,
data-model.md is missing), the corresponding tab is hidden from the canvas — no broken-link tab.
References
