msd-core/get-shit-done/workflows/help/modes/topic.md at 9bee1cab7fba00a8c0dec32d286913d36615f5bd

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

5.0 KiB

Raw Blame History

Emit a section from the full reference for the topic in `$ARGUMENTS`. Read `workflows/help/modes/full.md`, resolve the topic alias to a section heading using the table below, and output the resolved-routing preamble plus the section content. Scope is controlled by a `--brief` flag in `$ARGUMENTS`: full scope (default) emits the entire section; compact scope (`--brief `) emits only the signature line + one-line summary for a compact scoped lookup. No additions, no surrounding chrome. **Topic resolution table.** Match the topic alias case-insensitively. Strip a single leading `--` if present.

Topic alias(es)	Section heading in `full.md`
`workflow`, `core`, `core-workflow`	`## Core Workflow` (entire section through end of `### Quick Mode`)
`init`, `new-project`	`### Project Initialization`
`map`, `map-codebase`	The `/gsd:map-codebase` block under `### Project Initialization`
`discuss`, `discuss-phase`	The `/gsd:discuss-phase` block under `### Phase Planning`
`plan`, `planning`, `plan-phase`	`### Phase Planning`
`execute`, `exec`, `execute-phase`	`### Execution`
`progress`, `route`	`### Progress Tracking` plus `### Smart Router`
`quick`, `quick-mode`	`### Quick Mode`
`fast`	The `/gsd:fast` block under `### Quick Mode`
`phase`, `phases`, `roadmap`	`### Roadmap Management`
`milestone`, `milestones`	`### Milestone Management` plus `### Milestone Auditing`
`session`, `pause`, `resume`	`### Session Management`
`debug`, `debugging`	`### Debugging`
`spike`	The `/gsd:spike` and `/gsd:spike --wrap-up` blocks under `### Spiking & Sketching`
`sketch`	The `/gsd:sketch` and `/gsd:sketch --wrap-up` blocks under `### Spiking & Sketching`
`spike-sketch`, `experiments`	`### Spiking & Sketching`
`capture`, `notes`, `todos`	`### Capturing Ideas, Notes, and Todos`
`verify`, `verify-work`, `uat`	`### User Acceptance Testing` plus the `/gsd:audit-uat` block
`ship`, `pr`	`### Ship Work` plus the `/gsd:pr-branch` block
`review`, `peer-review`	The `/gsd:review` block under `### Ship Work`
`audit`, `auditing`, `audit-milestone`	`### Milestone Auditing`
`config`, `settings`, `configuration`	`### Configuration`
`cleanup`	The `/gsd:cleanup` block under `### Utility Commands`
`update`	The `/gsd:update` block under `### Utility Commands`
`files`, `structure`, `layout`	`## Files & Structure`
`modes`, `interactive`, `yolo`	`## Workflow Modes`
`planning-config`	`## Planning Configuration`
`workflows`, `common-workflows`, `examples`	`## Common Workflows`
`help`	`## Getting Help`

Output rules:

Parse $ARGUMENTS: detect a --brief (or -b) flag — this selects compact scope. Otherwise scope is full. Strip the flag, then take the remaining token (with a single leading -- stripped) as the topic alias.
Resolve the alias against the table.
If no match: emit a one-line error followed by a comma-separated list of the canonical topic names from the leftmost column (one per row, deduplicated). Suggest /gsd:help --full for the complete reference. Stop.
If matched: emit a single resolved-routing preamble line so the user sees what was matched:
```
**Topic:** `<alias>` → `<heading>` *(scope: full | compact)*
```
Use the canonical alias from the leftmost column. Use the literal heading text from the matched cell. State the scope you are about to emit.
Read workflows/help/modes/full.md. Strip <reference> / </reference> wrapper tags — never emit them. Apply the extraction rule for the matched table cell, modulated by scope:

5a. Single section (cell contains a single `## Heading` or `### Heading`):
- Full scope: emit from that heading up to (but not including) the next sibling or higher-level heading.
- Compact scope: emit the heading, then the first **`/gsd:...`** bold line within the section (the signature) and the single non-blank line immediately after it (the one-line summary). If the section has no **`/gsd:...`** bold line, emit the heading and the first paragraph.
5b. Multiple sections joined by "plus": apply rule 5a to each listed section in document order and emit them sequentially with no gap between them.

5c. Sub-block (cell says the /gsd:X block under ### Heading or the /gsd:X ... blocks under ### Heading): within the named heading's section, start at each **`/gsd:X ...`** bold line.
- Full scope: stop immediately before the next **`/gsd:...`** bold line or the next heading, whichever comes first.
- Compact scope: emit the bold line and the single non-blank line immediately after it (the one-line summary).
For cells listing multiple sub-blocks, emit them sequentially.

After the section content, emit a single closing line:

More: /gsd:help --full · /gsd:help <topic> · /gsd:help --brief <topic>

No project-specific commentary, no follow-up questions.

5.0 KiB Raw Blame History

5.0 KiB

Raw Blame History