msd-core/get-shit-done/workflows/help.md at 334a64168e44506f7a2134bb34613d4d37cb4401

Files

Andreas Brauchli 6a2bf05de7 feat(#3039 ): tier /gsd-help output (--brief, default, --full, <topic>) (#3040 )

Replace the single 747-line /gsd-help reference with a progressive-disclosure
dispatcher (#2551 pattern). Newcomers get a one-page tour; returning users get
a 10-line refresher with --brief; the complete reference stays available behind
--full; /gsd-help <topic> emits one section; and /gsd-help --brief <topic>
is a compact scoped lookup (signature + one-line summary).

- workflows/help.md becomes a small dispatcher routing on $ARGUMENTS
- workflows/help/modes/{brief,default,full,topic}.md hold the tier bodies
- commands/gsd/help.md passes $ARGUMENTS through, advertises composable form
- docs/COMMANDS.md documents the new flags and topic form
- existing tests that read help.md repointed at help/modes/full.md
  (bug-2836, bug-2950, bug-2954, cursor-reviewer, execute-phase-wave)
- new feat-3039-help-tiered test enforces structure, size budgets,
  dispatcher routing, shim arg passthrough, topic→section coverage,
  orphan-heading detection, conflict-resolution rules, routing preamble,
  and compact-scope rule

Trek-e review fixes (PR #3040):
- topic.md output rules split into 5a/5b/5c — explicit handling for single
  sections, multi-section "plus" joins, and bold-line sub-block anchors;
  each rule also takes scope (full vs compact) into account
- explicit resolved-routing preamble line emitted by topic.md before content
  ("**Topic:** `<alias>` → `<heading>` *(scope: full | compact)*") so the
  user sees which alias matched at which scope (review finding #3)
- composable `--brief <topic>` invokes topic.md in compact scope: heading
  + first `**/gsd:*`** signature line + one-line summary. Dispatcher and
  topic.md cooperate via $ARGUMENTS pass-through (review finding #4)
- full.md capped at LARGE-tier budget (FULL_BUDGET = 1500); the non-recursive
  workflow-size-budget test does not reach modes/ subdirs
- structural <progressive_disclosure> table parse (5-row assertion) replaces
  substring-soup regex matching — 5 rows = 4 base tiers + composable scope
- forward /gsd:* sub-block token coverage + reverse orphan-heading allowlist
  catch alias-table drift in both directions
- four conflict-resolution tests guard dispatcher promises (--brief+--full
  without topic → --full; --brief <topic> → compact; --full <topic> or bare
  → full; dispatcher retains --brief when delegating to topic.md)
- hardcoded topic lists removed from docs/COMMANDS.md and full.md (drift
  surfaces reduced from 5 to 2)
- topic.md alias bloat trimmed (~75 → ~25 rows); cleanup/update split into
  distinct sub-block rows under ### Utility Commands
- comment-rot ("~750 lines") removed from default.md and full.md
- dispatcher size guard tightened from < 100 to <= 40 lines
- commands/gsd/help.md <process> block trimmed to one line
- MD040 fence languages added to all plain code blocks across mode files

Main-merge conflict resolution:
- workflows/help.md kept as dispatcher (body lives in help/modes/full.md)
- /gsd-<cmd> → /gsd:<cmd> rename from #3452 reapplied to the mode files
  (full.md, default.md, brief.md, topic.md) — the six namespace routers
  (/gsd-context, /gsd-ideate, /gsd-manage, /gsd-project, /gsd-quality,
  /gsd-workflow) and wildcards (/gsd-*) preserved in hyphen form per
  main's convention
- bug-2950 test combines branch's path repointing with main's namespaced
  replacement strings

2026-05-15 22:02:55 -04:00

1.7 KiB

Raw Blame History

Display GSD command help at the tier the user asked for. Output ONLY the reference content of the chosen mode. Do NOT add project-specific analysis, git status, next-step suggestions, or any commentary beyond the reference.

<progressive_disclosure> Mode files are lazy-loaded. Read only the one mode file that matches $ARGUMENTS, then output its <reference> body verbatim.

When `$ARGUMENTS` is	Read
`--brief` (or `-b`) alone	`workflows/help/modes/brief.md`
`--full` (or `-f`, `--all`) alone	`workflows/help/modes/full.md`
empty / unset	`workflows/help/modes/default.md`
`--brief <topic>` (or `-b <topic>`)	`workflows/help/modes/topic.md` in compact scope (signature + one-line summary of the matched section)
anything else — bare topic, `--full <topic>`, or topic with leading `--`	`workflows/help/modes/topic.md` in full scope (entire matched section)

Argument parsing rules:

Trim and lowercase $ARGUMENTS.
Recognize the long form, short form, and obvious aliases listed above.
A bare token like debug, --debug, capture, workflow, config is a topic — route to topic.md.
Multiple flags: --brief and --full are mutually exclusive — if both appear without a topic, prefer --full.
--brief combined with a topic invokes topic.md in compact scope; --full combined with a topic invokes topic.md in full scope (the default topic behavior). When passing arguments through to topic.md, retain the --brief flag so the mode can pick the right scope.

After loading the chosen mode, emit its <reference> block content directly. No additions, no project context, no suggestions. </progressive_disclosure>

1.7 KiB Raw Blame History

1.7 KiB

Raw Blame History