iterative-works/iw-cli

Watch

Fork 0

Regenerate docs/api and llms.txt for the undocumented core modules #440

New issue

Open

opened 2026-08-23 19:29:17 +00:00 by mph · 6 comments

mph commented

2026-08-23 19:29:17 +00:00

Owner

docs/api/ and llms.txt describe a codebase that no longer exists.

Evidence

The last commit to touch the published copies is d52fce4 (2026-06-12). Since then roughly 22 modules were added under core/model|adapters|output with no page and no index line — among them:

WorktreeKey, EffortSlug, ForgeConfig, ForgejoUrl, ForgejoClient, Herdr, TerminalWorkspaceBackend, WorkflowGate, CiGate, CiLog, DashboardJar

and a further ~24 modules and 9 command scripts changed.

Why it went unnoticed

.claude/skills/build-iw-cli-skills/SKILL.md:66 states the staleness rule: a changed file under core/model/ stales its module page. IW-423 Phase 2 followed that rule and refreshed docs/api/ServerTypes.md, docs/api/Constants.md and llms.txt — the two pages it staled — which touched none of the missing 22.

Lesson: a staleness rule keyed on "the page for a changed module" cannot detect a module that never had a page, so the index silently stops describing the codebase.

Fix

Regenerate docs/api/ and llms.txt for the undocumented core modules.
Give build-iw-cli-skills a check for modules that have no page at all, not only pages that went stale.

Index lines were deliberately not added for the missing modules during IW-423, because a link to a docs/<Module>.md that does not exist is worse than no line.

Recorded during IW-423; see project-management/issues/IW-423/LESSONS.md entry 17.

`docs/api/` and `llms.txt` describe a codebase that no longer exists. ## Evidence The last commit to touch the published copies is `d52fce4` (2026-06-12). Since then roughly 22 modules were added under `core/model|adapters|output` with no page and no index line — among them: `WorktreeKey`, `EffortSlug`, `ForgeConfig`, `ForgejoUrl`, `ForgejoClient`, `Herdr`, `TerminalWorkspaceBackend`, `WorkflowGate`, `CiGate`, `CiLog`, `DashboardJar` and a further ~24 modules and 9 command scripts changed. ## Why it went unnoticed `.claude/skills/build-iw-cli-skills/SKILL.md:66` states the staleness rule: a changed file under `core/model/` stales its module page. IW-423 Phase 2 followed that rule and refreshed `docs/api/ServerTypes.md`, `docs/api/Constants.md` and `llms.txt` — the two pages it staled — which touched none of the missing 22. **Lesson:** a staleness rule keyed on "the page for a changed module" cannot detect a module that never had a page, so the index silently stops describing the codebase. ## Fix - Regenerate `docs/api/` and `llms.txt` for the undocumented core modules. - Give `build-iw-cli-skills` a check for modules that have no page at all, not only pages that went stale. Index lines were deliberately not added for the missing modules during IW-423, because a link to a `docs/<Module>.md` that does not exist is worse than no line. --- Recorded during IW-423; see `project-management/issues/IW-423/LESSONS.md` entry 17.

mph referenced this issue from a commit

2026-08-23 20:00:59 +00:00

workflow: Triage lessons for IW-423

mph referenced this issue

2026-08-27 08:05:50 +00:00

Help must be able to guide an agent: an overview index, and a --help on every command that prints instead of executing #463

mph referenced this issue from a commit

2026-09-02 21:08:30 +00:00

docs(api): index every core module and document the modules the gate work touched

mph referenced this issue

2026-09-02 21:08:30 +00:00

Regenerate the core module index and document the modules the gate work touched #503

mph referenced this issue

2026-09-11 18:18:16 +00:00

llms.txt links every module page as docs/<Module>.md, but the pages live in docs/api/ #543

claude commented

2026-09-22 06:25:50 +00:00

Member

Found during IW-601 phase 4 (§8): an existing page is also stale, not only missing ones. docs/api/PhaseMerge.md still lists CICheckStatus, CIVerdict, evaluateChecks and buildRecoveryPrompt, none of which exist in core/model/PhaseMerge.scala any more.

Found during IW-601 phase 4 (§8): an existing page is also stale, not only missing ones. `docs/api/PhaseMerge.md` still lists `CICheckStatus`, `CIVerdict`, `evaluateChecks` and `buildRecoveryPrompt`, none of which exist in `core/model/PhaseMerge.scala` any more.

mph referenced this issue from a commit

2026-09-22 13:34:13 +00:00

workflow: Triage lessons for IW-601

claude commented

2026-10-02 08:45:31 +00:00

Member

More stale output found during IW-652. One build-iw-cli-skills run regenerates both:

Regenerate docs/api/ with the build-iw-cli-skills flow: it still documents the old ServerStatus (running, pid) and ServerLifecycleService.createStatus, which IW-652 Phase 1 removed.
The published skills (build-iw-cli-skills) need iw service and the WorktreeServices API.

More stale output found during IW-652. One `build-iw-cli-skills` run regenerates both: - Regenerate `docs/api/` with the `build-iw-cli-skills` flow: it still documents the old `ServerStatus` (`running`, `pid`) and `ServerLifecycleService.createStatus`, which IW-652 Phase 1 removed. - The published skills (`build-iw-cli-skills`) need `iw service` and the `WorktreeServices` API.

mph referenced this issue from a commit

2026-10-02 08:47:47 +00:00

workflow: Triage lessons for IW-652

claude referenced this issue

2026-10-02 08:48:04 +00:00

IW-652: Per-user dashboard on a shared dev machine — tailnet service, service links, Claude session links #683

claude referenced this issue

2026-10-06 21:28:05 +00:00

llms.txt and docs/api lag the core modules #725

claude commented

2026-10-08 02:50:34 +00:00

Member

Found during IW-682 (port allocation for worktrees). Follow-up, verbatim:

After Phase 2, regenerate the published skills (build-iw-cli-skills) for iw port-slot and the WorktreePortSlots API.

Found during IW-682 (port allocation for worktrees). Follow-up, verbatim: - [ ] After Phase 2, regenerate the published skills (build-iw-cli-skills) for `iw port-slot` and the `WorktreePortSlots` API.

mph referenced this issue from a commit

2026-10-08 02:53:06 +00:00

chore(IW-682): file follow-ups (#440, #585, #754, #755, #756)

claude referenced this issue

2026-10-08 02:53:36 +00:00

IW-682: Port allocation for worktrees (iw port-slot) #757

claude commented

2026-10-11 00:18:05 +00:00

Member

Found during IW-513 (phase 3), for the regeneration:

llms.txt lists GitHubClient twice under Adapters.

Found during IW-513 (phase 3), for the regeneration: - [ ] `llms.txt` lists `GitHubClient` twice under Adapters.

mph referenced this issue from a commit

2026-10-11 00:19:19 +00:00

chore(IW-513): file follow-ups (IW-781; comments on #569, #585, #762, #440)

claude referenced this issue

2026-10-11 00:20:49 +00:00

IW-513: phase-pr tells a forge that is down from a forge that refused #782

claude commented

2026-10-11 03:15:14 +00:00

Member

From IW-548 follow-ups:

docs/api/ReviewStateCliParser.md shows a stale resolveIssueId body — docs/api/ReviewStateCliParser.md (~lines 319-327) shows a resolveIssueId body that no longer matches ReviewState.scala, which now uses WorktreeKeyResolver.fromFlagOrBranch; refresh the example.

From IW-548 follow-ups: - [ ] `docs/api/ReviewStateCliParser.md` shows a stale `resolveIssueId` body — `docs/api/ReviewStateCliParser.md` (~lines 319-327) shows a `resolveIssueId` body that no longer matches `ReviewState.scala`, which now uses `WorktreeKeyResolver.fromFlagOrBranch`; refresh the example.

mph referenced this issue from a commit

2026-10-11 03:16:40 +00:00

chore(IW-548): file follow-up on #440

claude referenced this issue

2026-10-11 03:16:57 +00:00

IW-548: a non-repeatable valued flag given twice takes the last value everywhere #786

claude commented

2026-10-16 03:11:21 +00:00

Member

Intake: needs-human
Workflow: waterfall
Reason: G7 a standing [fix] finding — the analysis gives CommandDocsDriftTest as the precedent for a pin that requires every module to have a page, but that test asserts the opposite direction (D8.1 = A); also open: G7 (1 [human] finding: should the module-coverage check be a blocking CI pin, a skill-only check, or a warning)
Analysis: project-management/issues/IW-440/analysis.md on branch IW-440

Intake: needs-human Workflow: waterfall Reason: G7 a standing [fix] finding — the analysis gives CommandDocsDriftTest as the precedent for a pin that requires every module to have a page, but that test asserts the opposite direction (D8.1 = A); also open: G7 (1 [human] finding: should the module-coverage check be a blocking CI pin, a skill-only check, or a warning) Analysis: project-management/issues/IW-440/analysis.md on branch IW-440

claude added the

needs-human

label

2026-10-16 03:11:21 +00:00