From 120e7983ae50d9b87807dfff69d9399c45f6ecd9 Mon Sep 17 00:00:00 2001 From: Jon Langevin Date: Thu, 4 Jun 2026 21:47:22 -0400 Subject: [PATCH] docs(mcp): retrospective + scope-lock complete for #854 Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/plans/2026-06-04-mcp-cigen-info.md | 2 +- .../2026-06-04-mcp-cigen-info.md.scope-lock | 1 - docs/retros/2026-06-04-mcp-cigen-info.md | 33 +++++++++++++++++++ 3 files changed, 34 insertions(+), 2 deletions(-) delete mode 100644 docs/plans/2026-06-04-mcp-cigen-info.md.scope-lock create mode 100644 docs/retros/2026-06-04-mcp-cigen-info.md diff --git a/docs/plans/2026-06-04-mcp-cigen-info.md b/docs/plans/2026-06-04-mcp-cigen-info.md index d2f1b67b8..be44edf63 100644 --- a/docs/plans/2026-06-04-mcp-cigen-info.md +++ b/docs/plans/2026-06-04-mcp-cigen-info.md @@ -31,7 +31,7 @@ |------|-------|-------|--------| | 1 | docs(mcp): surface cigen config-derived CI generation in MCP output | Task 1, Task 2, Task 3, Task 4, Task 5, Task 6, Task 7 | feat/mcp-cigen-info | -**Status:** Locked 2026-06-05T01:05:30Z +**Status:** Complete 2026-06-05T01:47:12Z --- diff --git a/docs/plans/2026-06-04-mcp-cigen-info.md.scope-lock b/docs/plans/2026-06-04-mcp-cigen-info.md.scope-lock deleted file mode 100644 index 79a6eb8a5..000000000 --- a/docs/plans/2026-06-04-mcp-cigen-info.md.scope-lock +++ /dev/null @@ -1 +0,0 @@ -2d992e2e622762acab9c04aa3f7c6123d845749abcfa8d16c1f878d19c3fa3b4 diff --git a/docs/retros/2026-06-04-mcp-cigen-info.md b/docs/retros/2026-06-04-mcp-cigen-info.md new file mode 100644 index 000000000..9a410cf55 --- /dev/null +++ b/docs/retros/2026-06-04-mcp-cigen-info.md @@ -0,0 +1,33 @@ +# Retro — surface cigen info in wfctl MCP output (#854) + +**Date:** 2026-06-04 +**PR:** GoCodeAlone/workflow#854 (merged b482dff2b) +**Design:** docs/plans/2026-06-04-mcp-cigen-info-design.md +**Plan:** docs/plans/2026-06-04-mcp-cigen-info.md + +## What shipped + +Informational accuracy fix: wfctl's MCP output now describes the config-derived **cigen** CI generation. 5 surfaces + a `Contains` test: +- `mcp/server.go` Instructions (extracted to a `serverInstructions` const so it's testable), `mcp/docs.go` `docsOverview`, `mcp/wfctl_tools.go` (`ci_plan`/`generate_github_actions` descriptions), `mcp/setup_guide.go` CI/CD flow, `docs/mcp-tools-reference.md` (added the absent `ci_plan`/`generate_github_actions` entries + corrected the stale `scaffold_ci` entry). +- No new tools, no handler/behavior change, no release. The render path was already cigen-backed; only the *information* was stale. + +## What the gates caught (and it was a lot, for a "doc change") + +- **Design adversarial (2 cycles)** killed a self-inflicted factual error: the design claimed "Jenkins/CircleCI are template-based" — contradicting `docs/WFCTL.md:2142` (all four platforms are config-derived from the same CIPlan; workflow#810/ADR 0044). Also surfaced a **missed surface**: the `workflow://docs/setup-guide` resource + `scaffold_ci`/`generate_bootstrap` route the AI to a *different*, non-cigen CI flow — left unmentioned, the MCP would self-contradict on the very topic being fixed. Both fixed (all-four-config-derived; setup-guide "two CI paths" note). +- **Plan adversarial** verified the mcp-go API types (`ListTools()` → `map[string]*server.ServerTool`, `.Tool.Description`) and **ran the Task 7 runtime handshake live** before approving. +- **Copilot review** (functional again) found **4 real accuracy bugs** in the descriptions — ironic for an accuracy PR, but correct: the MCP `generate_github_actions` tool **re-analyzes from `yaml_content`** (it does NOT accept a pre-built/edited CIPlan) and renders **GitHub Actions only** (not GitLab); editing-then-rendering is the CLI `--from-plan` path. The descriptions implied otherwise. Also: the test *claimed* to lock the Instructions but never asserted them. All 4 addressed (clarified render-tool semantics; extracted `serverInstructions` const + asserted it). + +## Lessons + +- **"Informational" changes still need the full pipeline.** Three independent gates (design adversarial, Copilot, and the runtime check) each caught a distinct factual error that would have shipped *wrong* documentation — the worst outcome for an accuracy fix. The design self-challenge alone would not have caught the Jenkins/CircleCI error (I wrote it confidently). +- **Describe what the MCP tool *actually does*, not what the CLI does.** The cigen CLI (`wfctl ci generate`) supports `--from-plan` and all four platforms; the MCP `generate_github_actions` tool is a narrower surface (re-analyze, GHA-only). Conflating the two is the exact error class. Verify tool descriptions against the *handler*, not the CLI docs. → [[feedback_verify_artifact_exists_not_just_shape]] applies to tool *semantics*, not just existence. +- **Make claimed test coverage real.** A test comment that says "locks the Instructions" while asserting nothing about them is a latent gap Copilot rightly flagged; extracting the string to a package const made the assertion possible. + +## Follow-ups (logged in plan out-of-scope) + +- `generate_github_actions` handler reads `phase_config_yaml`/`wfctl_version` but the tool def does NOT declare them (latent schema gap) — clients can't discover them. Worth a small schema PR. +- `scaffold_environment`/`scaffold_infra` entries in `docs/mcp-tools-reference.md` also drift from their defs (not CI-related). + +## Gate tally + +design adversarial 2 cycles (C1 platform-coverage error, I1 missed setup-guide surface, I2 ref-doc format/stale scaffold_ci) + plan adversarial 1 cycle PASS (ran runtime handshake) + alignment PASS + scope-lock + code review + Copilot 4 findings addressed. 21/21 CI green → admin-merge.