refactor(bmad-spec): add lean-prose discipline + generalize help text
- Add Spec Law rule 8: lean prose. Every sentence carries load-bearing content; cut decoration, hedges, backstory, throat-clearing. Applies to SPEC.md, companions, and decision log. - Update Self-Validate Pass 1 to enforce rules 1-6 and 8 (rule 7 stays in Pass 2) - Prime the operation up-front: write lean from the first pass, every sentence must earn its place - Note in Companions section that companions follow the same lean discipline - Generalize core module-help.csv entry: domain-agnostic framing (software, game design, research, editorial, policy, business, anything intent-bearing); call out succinct, no-fluff and "locks the WHAT before the HOW" as the value props
This commit is contained in:
Brian Madison
parent
6a05148c45
commit
872ee46fd4
|
|
@ -55,6 +55,8 @@ When the input is structured and pre-sorted (a PRD with an addendum, a GDD, a br
|
|||
|
||||
Distill the input into the five-field kernel using `{workflow.spec_template}` as the skeleton. When input is rich, extract directly — no elicitation. When input is sparse, choose: **express** (best-effort distill, every gap becomes an `open_questions[]` entry) or **guided** (walk the five fields with the user one at a time). Headless defaults to express and logs the choice. Interactive asks.
|
||||
|
||||
Write lean from the first pass: every sentence must earn its place. Decoration costs tokens and dilutes downstream readers.
|
||||
|
||||
If the input is genuinely too thin to distill (e.g. "an app for hikers" with no surrounding context), stop and suggest `bmad-prd` (or sibling ceremony skill). This skill distills; it does not coach.
|
||||
|
||||
## Load-bearing
|
||||
|
|
@ -63,7 +65,7 @@ A claim is **load-bearing** if any consumer (downstream skill, implementing agen
|
|||
|
||||
## Companions
|
||||
|
||||
When load-bearing content does not fit the five-field kernel, it lives in a companion. The kernel cites it; the companion holds it. Companions are part of the contract; every consumer reads `companions:` in SPEC.md frontmatter to discover them.
|
||||
When load-bearing content does not fit the five-field kernel, it lives in a companion. The kernel cites it; the companion holds it. Companions are part of the contract; every consumer reads `companions:` in SPEC.md frontmatter to discover them. Companions follow the same lean discipline as SPEC.md (Spec Law rule 8).
|
||||
|
||||
**Spawn a companion when the content needs more than one kernel-shape line:** multi-item catalogs (per-entity matrices like archetypes, drinks, modes, routes), tables, diagrams (always), editorial voice rules, long-form reference material the kernel cites by name (glossary, brownfield notes, project conventions). Single-line decision-benders stay in Constraints; intent+success pairs stay in Capabilities. If a kernel field is starting to bullet into sub-bullets, the content has outgrown the kernel and wants a companion.
|
||||
|
||||
|
|
@ -81,7 +83,7 @@ Pre-existing project-wide docs (e.g. `project-context.md`) that downstream needs
|
|||
|
||||
## Spec Law
|
||||
|
||||
Every spec must satisfy these seven rules. The operation aims for them; the self-validate sweep enforces them.
|
||||
Every spec must satisfy these eight rules. The operation aims for them; the self-validate sweep enforces them.
|
||||
|
||||
1. **Each capability has both `intent` and `success`.** Missing either = not a capability.
|
||||
2. **Intents describe WHAT, not HOW.** Implementation prescription belongs in a companion (stack, conventions)..
|
||||
|
|
@ -90,12 +92,13 @@ Every spec must satisfy these seven rules. The operation aims for them; the self
|
|||
5. **Success signal is concrete enough to test or demonstrate against.** "Users love it" doesn't qualify.
|
||||
6. **Capability IDs are stable and unique.** Never reused, never renumbered.
|
||||
7. **Preservation.** Every load-bearing source claim lands in SPEC.md or a companion. Wrapper ceremony does not.
|
||||
8. **Lean prose.** Every sentence carries load-bearing content. Cut decoration, hedges, backstory, throat-clearing. Applies to SPEC.md, companions, and `.decision-log.md`.
|
||||
|
||||
## Self-Validate
|
||||
|
||||
After every create or update, sweep the resulting artifact in **two passes** before presenting.
|
||||
|
||||
**Pass 1 — Coherence.** Judge the spec against Spec Law rules 1–6. For anything that fails or feels weak, attempt to fix it without inventing content the input did not support. Calls made without direct confirmation become `assumptions[]`; gaps that could not be filled become `open_questions[]`.
|
||||
**Pass 1 — Coherence.** Judge the spec against Spec Law rules 1–6 and 8. For anything that fails or feels weak, attempt to fix it without inventing content the input did not support. Calls made without direct confirmation become `assumptions[]`; gaps that could not be filled become `open_questions[]`.
|
||||
|
||||
**Pass 2 — Preservation.** Walk the source claim by claim. Confirm each load-bearing claim landed in SPEC.md or a companion. Wrapper-ceremony drops are logged under "Wrapper-only content" so the drop is on the record, not silent.
|
||||
|
||||
|
|
|
|||
|
|
@ -9,5 +9,5 @@ Core,bmad-editorial-review-prose,Editorial Review - Prose,EP,Use after drafting
|
|||
Core,bmad-editorial-review-structure,Editorial Review - Structure,ES,Use when doc produced from multiple subprocesses or needs structural improvement.,,[path],anytime,,,false,report located with target document,
|
||||
Core,bmad-review-adversarial-general,Adversarial Review,AR,"Use for quality assurance or before finalizing deliverables. Code Review in other modules runs this automatically, but also useful for document reviews.",,[path],anytime,,,false,,
|
||||
Core,bmad-review-edge-case-hunter,Edge Case Hunter Review,ECH,Use alongside adversarial review for orthogonal coverage — method-driven not attitude-driven.,,[path],anytime,,,false,,
|
||||
Core,bmad-spec,Spec,SP,"Use to distill any intent input (PRD, GDD, brief, UX folder, transcript, mixed multi-source) into the canonical SPEC.md contract + companions for downstream skills (architecture, ticketing, quick-dev). Validation mode also available.",,[path],anytime,,,false,{planning_artifacts}/specs/spec-{slug}-{date},SPEC.md + companion files
|
||||
Core,bmad-spec,Spec,SP,"Use to distill any intent input (brief, PRD, transcript, brain dump, design folder, mixed multi-source) into a succinct, no-fluff SPEC.md contract + companions that downstream work derives from. Locks the WHAT before the HOW. Works for software, game design, research, editorial, policy, business, anything intent-bearing. Validation mode also available.",,[path],anytime,,,false,{planning_artifacts}/specs/spec-{slug}-{date},SPEC.md + companion files
|
||||
Core,bmad-customize,BMad Customize,BC,"Use when you want to change how an agent or workflow behaves — add persistent facts, swap templates, insert activation hooks, or customize menus. Scans what's customizable, picks the right scope (agent vs workflow), writes the override to _bmad/custom/, and verifies the merge. No TOML hand-authoring required.",,,anytime,,,false,{project-root}/_bmad/custom,TOML override files
|
||||
|
|
|
|||
|
Loading…
Reference in New Issue