Dashboard Feature Discovery

Surfacing Shipped-But-Undocumented CLI Features

Experiment Overview

Context

The user said "There was a feature to display a dashboard of project processing progress. I don't see it in the repo README or the readthedocs.io."

/advise against Skills_Registry/plugins/kintsugi/ returned 0 hits for "dashboard". A direct Grep dashboard against the repo returned 5 matches:

• src/kintsugi/dashboard.py — 1200+ line module with scan_project_progress, render_dashboard, watch_dashboard, estimate_completion
• src/kintsugi/cli.py — @workflow.command("status") plus --dashboard flag on workflow run
• tests/test_dashboard.py — full test coverage
• CLAUDE.md — agent-facing docs mention both entry points

README.md and docs/ returned 0 matches. The feature shipped, was tested, and was documented for Claude — but never advertised to humans. This is a recurring failure mode: a developer adds a CLI command, updates CLAUDE.md so the AI assistant knows about it, and forgets the user-facing surfaces.

Verified Workflow

1. Confirm the feature actually exists

Before assuming it was deleted or renamed, grep for the feature name across the whole repo (not just docs):

# Search code, tests, AND docs
Grep "dashboard|workflow_status" --output_mode files_with_matches

If matches appear only in src/, tests/, and CLAUDE.md but not README.md / docs/, you have a documentation gap, not a missing feature.

2. Read the implementation to extract the public surface

Open the CLI command definition and the underlying module to enumerate:

• All flags and their defaults
• All entry points (e.g., standalone workflow status AND embedded workflow run --dashboard)
• What each section of the rendered output actually shows
• Which functions are the public API (so docs can name them for code spelunkers)

For the KINTSUGI dashboard:

3. Match the existing docs style — do not invent a new format

Read a peer doc (e.g., docs/cli.md for a sibling command, README.md for the section conventions) and mirror:

• Heading depth
• Code-block flags
• Whether examples use /path/to/project or .
• Whether tables describe flags or prose does
• Where the section sits in the table of contents

For KINTSUGI: docs/cli.md already had ### kintsugi workflow run with a code block — the new ### kintsugi workflow status slots in immediately after, mirroring the same shape. README's ## HPC/SLURM Job Submission has a flat list of subsections — add ### Progress Dashboard between "Snakemake Workflow" and "Monitoring and Logs".

4. Update the README in TWO places

A README update isn't done until both:

• The Table of Contents has the new anchor
• The new section exists at the right heading level

Forgetting the TOC entry leaves the section unreachable from the top of the README.

5. Write a retrospective skill

The whole reason this happened is that nobody documented the rule "user-facing CLI commands must land in README + docs/, not just CLAUDE.md." Save it as a skill so /advise finds it next time.

Failed Attempts (Critical)

Final Parameters

Key Insights

• A feature can ship, be tested, and be documented for the AI assistant without ever reaching users. CLAUDE.md is agent-facing context — it does not count as user documentation.
• Two entry points are easy to miss. A workflow run --dashboard flag is structurally separate from a workflow status subcommand. Always read the CLI module end-to-end for references to the feature name.
• Grepping docs/ is not enough to confirm absence. Grep the whole repo — if matches appear in src/ and tests/ but not README.md/docs/, you have a documentation gap, not a deleted feature.
• README and docs are separate surfaces with different jobs. README is the entry point for new users (short, high-signal); docs/cli.md is the reference (exhaustive flag list). Both need updates — neither is sufficient alone.
• The TOC is part of the section. A new heading without a matching TOC anchor is half-done.
• Always retrospective the gap, not just the fix. The next missing feature will be found the same way; saving a skill makes the discovery process repeatable.

Results

References

• src/kintsugi/dashboard.py — scan_project_progress, render_dashboard, watch_dashboard, estimate_completion
• src/kintsugi/cli.py:1898 — _run_with_dashboard() (embedded variant)
• src/kintsugi/cli.py:2188 — @workflow.command("status") (standalone variant)
• tests/test_dashboard.py — coverage