Surfacing Shipped-But-Undocumented CLI Features
Experiment Overview
| Item |
Details |
| Date |
2026-04-08 |
| Goal |
Document the kintsugi workflow status / workflow run --dashboard progress dashboard in README + readthedocs after the user reported it missing |
| Environment |
KINTSUGI repo, src/kintsugi/dashboard.py, src/kintsugi/cli.py, docs/cli.md, README.md |
| Status |
Success |
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:
| Surface |
Where |
| Standalone CLI |
kintsugi workflow status (cli.py workflow_status) |
| Embedded CLI |
kintsugi workflow run --dashboard (cli.py _run_with_dashboard) |
| Public API |
scan_project_progress, render_dashboard, watch_dashboard, estimate_completion in dashboard.py |
| Flags |
--watch/-w, --interval/-i, --all-projects, --json, --no-hardware, --no-estimates, --no-jobs |
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)
| Attempt |
Why it Failed |
Lesson Learned |
Searching only docs/ for "dashboard" |
Returned 0 hits; could have falsely concluded the feature was deleted |
Always grep the whole repo before declaring a feature missing — src/, tests/, and CLAUDE.md are the source of truth for "does it exist" |
Documenting only the standalone workflow status command |
Missed the embedded workflow run --dashboard entry point — users would discover only half the feature |
Read cli.py end-to-end for all references to the feature, not just the obvious command |
| Adding a new section to README without updating the Table of Contents |
Section was unreachable from the TOC anchor list at the top |
A README edit isn't done until the TOC entry exists too |
| Treating CLAUDE.md as user documentation |
CLAUDE.md is agent-facing context, not user-facing docs — users don't read it |
User-facing CLI commands live in README.md + docs/cli.md; CLAUDE.md is a separate, agent-only surface |
| Inventing a new doc format for the new section |
Inconsistency makes the docs feel unmaintained |
Mirror the heading depth, table style, and example format of the closest peer command in the same file |
Final Parameters
| Parameter |
Value |
Rationale |
| Discovery grep scope |
Whole repo (src/, tests/, CLAUDE.md, README.md, docs/) |
Lets you distinguish "missing" from "undocumented" |
| README placement |
New ### Progress Dashboard subsection inside ## HPC/SLURM Job Submission |
Adjacent to the workflow commands users already know about |
| TOC update |
Mandatory in the same edit as the section |
Otherwise the section is unreachable |
| docs/ placement |
New ### kintsugi workflow status block in docs/cli.md, plus a --dashboard example added to ### kintsugi workflow run |
Both entry points need a home |
| Cross-reference |
Each new section names the source files (src/kintsugi/dashboard.py, public function names) |
Lets future maintainers find the implementation |
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
| Surface |
Before |
After |
README.md mentions of "dashboard" |
0 |
9 (new section + TOC entry) |
docs/cli.md mentions of "dashboard" |
0 |
7 (workflow status block + workflow run --dashboard example) |
CLAUDE.md mentions |
5 (already documented for agent) |
unchanged |
| Source/tests |
src/kintsugi/dashboard.py, tests/test_dashboard.py |
unchanged (already shipped) |
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
1---
2name: dashboard-feature-discovery
3description: "Surface a shipped-but-undocumented CLI feature in user-facing docs. Trigger: user reports a known feature missing from README/readthedocs even though the CLI command exists."
4author: KINTSUGI Team
5date: 2026-04-08
6metadata:
7 source: https://skillmd.com/skills/smith6jt-cop/dashboard-feature-discovery
8---
9
10# Surfacing Shipped-But-Undocumented CLI Features
11
12## Experiment Overview
13
14| Item | Details |
15|------|---------|
16| **Date** | 2026-04-08 |
17| **Goal** | Document the `kintsugi workflow status` / `workflow run --dashboard` progress dashboard in README + readthedocs after the user reported it missing |
18| **Environment** | KINTSUGI repo, `src/kintsugi/dashboard.py`, `src/kintsugi/cli.py`, `docs/cli.md`, `README.md` |
19| **Status** | Success |
20
21## Context
22
23The 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."
24
25`/advise` against `Skills_Registry/plugins/kintsugi/` returned 0 hits for "dashboard". A direct `Grep dashboard` against the repo returned **5** matches:
26
27- `src/kintsugi/dashboard.py` — 1200+ line module with `scan_project_progress`, `render_dashboard`, `watch_dashboard`, `estimate_completion`
28- `src/kintsugi/cli.py` — `@workflow.command("status")` plus `--dashboard` flag on `workflow run`
29- `tests/test_dashboard.py` — full test coverage
30- `CLAUDE.md` — agent-facing docs mention both entry points
31
32`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.
33
34## Verified Workflow
35
36### 1. Confirm the feature actually exists
37
38Before assuming it was deleted or renamed, grep for the feature name across the *whole* repo (not just docs):
39
40```bash
41# Search code, tests, AND docs
42Grep "dashboard|workflow_status" --output_mode files_with_matches
43```
44
45If matches appear only in `src/`, `tests/`, and `CLAUDE.md` but not `README.md` / `docs/`, you have a documentation gap, not a missing feature.
46
47### 2. Read the implementation to extract the public surface
48
49Open the CLI command definition and the underlying module to enumerate:
50
51- All flags and their defaults
52- All entry points (e.g., standalone `workflow status` AND embedded `workflow run --dashboard`)
53- What each section of the rendered output actually shows
54- Which functions are the public API (so docs can name them for code spelunkers)
55
56For the KINTSUGI dashboard:
57
58| Surface | Where |
59|---------|-------|
60| Standalone CLI | `kintsugi workflow status` (`cli.py` `workflow_status`) |
61| Embedded CLI | `kintsugi workflow run --dashboard` (`cli.py` `_run_with_dashboard`) |
62| Public API | `scan_project_progress`, `render_dashboard`, `watch_dashboard`, `estimate_completion` in `dashboard.py` |
63| Flags | `--watch/-w`, `--interval/-i`, `--all-projects`, `--json`, `--no-hardware`, `--no-estimates`, `--no-jobs` |
64
65### 3. Match the existing docs style — do not invent a new format
66
67Read a peer doc (e.g., `docs/cli.md` for a sibling command, `README.md` for the section conventions) and mirror:
68
69- Heading depth
70- Code-block flags
71- Whether examples use `/path/to/project` or `.`
72- Whether tables describe flags or prose does
73- Where the section sits in the table of contents
74
75For 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".
76
77### 4. Update the README in TWO places
78
79A README update isn't done until both:
80
81- The **Table of Contents** has the new anchor
82- The new section exists at the right heading level
83
84Forgetting the TOC entry leaves the section unreachable from the top of the README.
85
86### 5. Write a retrospective skill
87
88The 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.
89
90## Failed Attempts (Critical)
91
92| Attempt | Why it Failed | Lesson Learned |
93|---------|---------------|----------------|
94| Searching only `docs/` for "dashboard" | Returned 0 hits; could have falsely concluded the feature was deleted | Always grep the whole repo before declaring a feature missing — `src/`, `tests/`, and `CLAUDE.md` are the source of truth for "does it exist" |
95| Documenting only the standalone `workflow status` command | Missed the embedded `workflow run --dashboard` entry point — users would discover only half the feature | Read `cli.py` end-to-end for all references to the feature, not just the obvious command |
96| Adding a new section to README without updating the Table of Contents | Section was unreachable from the TOC anchor list at the top | A README edit isn't done until the TOC entry exists too |
97| Treating CLAUDE.md as user documentation | CLAUDE.md is agent-facing context, not user-facing docs — users don't read it | User-facing CLI commands live in **README.md + docs/cli.md**; CLAUDE.md is a separate, agent-only surface |
98| Inventing a new doc format for the new section | Inconsistency makes the docs feel unmaintained | Mirror the heading depth, table style, and example format of the closest peer command in the same file |
99
100## Final Parameters
101
102| Parameter | Value | Rationale |
103|-----------|-------|-----------|
104| Discovery grep scope | Whole repo (`src/`, `tests/`, `CLAUDE.md`, `README.md`, `docs/`) | Lets you distinguish "missing" from "undocumented" |
105| README placement | New `### Progress Dashboard` subsection inside `## HPC/SLURM Job Submission` | Adjacent to the workflow commands users already know about |
106| TOC update | Mandatory in the same edit as the section | Otherwise the section is unreachable |
107| docs/ placement | New `### kintsugi workflow status` block in `docs/cli.md`, plus a `--dashboard` example added to `### kintsugi workflow run` | Both entry points need a home |
108| Cross-reference | Each new section names the source files (`src/kintsugi/dashboard.py`, public function names) | Lets future maintainers find the implementation |
109
110## Key Insights
111
112- **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.
113- **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.
114- **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.
115- **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.
116- **The TOC is part of the section.** A new heading without a matching TOC anchor is half-done.
117- **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.
118
119## Results
120
121| Surface | Before | After |
122|---------|--------|-------|
123| `README.md` mentions of "dashboard" | 0 | 9 (new section + TOC entry) |
124| `docs/cli.md` mentions of "dashboard" | 0 | 7 (`workflow status` block + `workflow run --dashboard` example) |
125| `CLAUDE.md` mentions | 5 (already documented for agent) | unchanged |
126| Source/tests | `src/kintsugi/dashboard.py`, `tests/test_dashboard.py` | unchanged (already shipped) |
127
128## References
129
130- `src/kintsugi/dashboard.py` — `scan_project_progress`, `render_dashboard`, `watch_dashboard`, `estimate_completion`
131- `src/kintsugi/cli.py:1898` — `_run_with_dashboard()` (embedded variant)
132- `src/kintsugi/cli.py:2188` — `@workflow.command("status")` (standalone variant)
133- `tests/test_dashboard.py` — coverage