feat(quickstart): emit topic breadcrumbs in mutation-command success output (lit-c5519f81-93c728d5.2.2)#205
Merged
Conversation
…output (lit-c5519f81-93c728d5.2.2) Text success output of new/followup, start, done/close, and update/rank/label/parent/dep now ends with a one-line pointer at the matching quickstart topic, so discovery of task guidance happens at the moment of need rather than only at session start. The breadcrumb rides the text printer via withQuickstartBreadcrumb, so printValue's existing single-enforcer routing keeps JSON mode structurally breadcrumb-free on every stream. Tokens are validated against the quickstartTopics table at wrap time and fail loudly on a wiring typo; transition actions map to topics through a lookup table where absence encodes 'no follow-on topic'.
There was a problem hiding this comment.
Z.ai Coding Agent Review
No must-change items. The breadcrumb feature is cleanly structured:
- Data-driven wiring:
transitionBreadcrumbTopicsis a lookup table;withQuickstartBreadcrumbis a composable wrapper over any text printer. Theif okmap-lookup inrunTransitionis Go's standard map access, not a mode-flag branch — the data (map presence/absence) decides the behavior. - [LAW:one-source-of-truth]: Topic tokens derive from the canonical
quickstartTopicstable.quickstartBreadcrumbvalidates at a single point;TestTransitionBreadcrumbTopicsAreValidTokenscatches wiring drift. - [LAW:no-silent-failure]:
quickstartBreadcrumbpanics loudly on unknown tokens (developer wiring error), consistent with failing hard on invalid internal state. - [LAW:single-enforcer]: JSON safety is structural —
printValueroutes JSON mode towriteJSONbefore any text printer runs, so breadcrumbs cannot reach the JSON contract. Tests verify both per-command--jsonand global JSON mode. - [LAW:behavior-not-structure]: Tests assert output content (breadcrumb text, JSON absence), not implementation. The rank-frame test update explicitly moves from positional assertions to content-based ones, noted inline.
Pre-existing note (unchanged code): the token type is string throughout, with runtime validation compensating for the loose type. A future tightening to named types would let the compiler catch wiring bugs that the current panic guard catches at runtime, but this diff doesn't introduce or worsen that looseness.
✅ Approved
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes lit-c5519f81-93c728d5.2.2 (epic: split quickstart into router + topic subcommands).
What
Mutation commands now end their text success output with a one-line breadcrumb pointing at the relevant
lit quickstart <topic>, so discovery of task guidance happens at the moment of need rather than only at session start:new,followuplit quickstart newstartlit quickstart readydone,closelit quickstart doneupdate,rank,rank set,label add/rm,parent set/clear,dep add/rmlit quickstart updateExample:
How
withQuickstartBreadcrumb(token, textFn)wraps the text printer passed toprintValue. SinceprintValueis the existing single enforcer that routes JSON mode towriteJSONbefore any text printer runs, JSON output is structurally breadcrumb-free on every stream — the machine contract is preserved by construction, not by guards.quickstartTopicstable at wrap time (panic on unknown token), so the topic list is never duplicated and a wiring typo dies in the first test run.transitionBreadcrumbTopics; absence from the table encodes "no natural follow-on topic" (archive, delete, reopen, ...).lit doneguided preview (pre-apply) carries no breadcrumb — only the actual success output does.Verification
--jsonforms.rank_frame_test.goupdated: it pinned "summary is the last line" (structure); now asserts the summary line describing the moved epic exists (behavior).go test ./...green; live-verified against a scratch repo (text breadcrumbs on new/start/label/done-apply, single-JSON-doc output under local and global--json).