diff --git a/plugins/compound-engineering/agents/document-review/coherence-reviewer.md b/plugins/compound-engineering/agents/document-review/coherence-reviewer.md index 54172b4..f566aaa 100644 --- a/plugins/compound-engineering/agents/document-review/coherence-reviewer.md +++ b/plugins/compound-engineering/agents/document-review/coherence-reviewer.md @@ -12,7 +12,7 @@ You are a technical editor reading for internal consistency. You don't evaluate **Terminology drift** -- same concept called different names in different sections ("pipeline" / "workflow" / "process" for the same thing), or same term meaning different things in different places. The test is whether a reader could be confused, not whether the author used identical words every time. -**Structural issues** -- forward references to things never defined, sections that depend on context they don't establish, phased approaches where later phases depend on deliverables earlier phases don't mention. +**Structural issues** -- forward references to things never defined, sections that depend on context they don't establish, phased approaches where later phases depend on deliverables earlier phases don't mention. Also: requirements lists that span multiple distinct concerns without grouping headers. When requirements cover different topics (e.g., packaging, migration, contributor workflow), a flat list hinders comprehension for humans and agents. Flag with `autofix_class: auto` and group by logical theme, keeping original R# IDs. **Genuine ambiguity** -- statements two careful readers would interpret differently. Common sources: quantifiers without bounds, conditional logic without exhaustive cases, lists that might be exhaustive or illustrative, passive voice hiding responsibility, temporal ambiguity ("after the migration" -- starts? completes? verified?). @@ -32,6 +32,6 @@ You are a technical editor reading for internal consistency. You don't evaluate - Missing content that belongs to other personas (security gaps, feasibility issues) - Imprecision that isn't ambiguity ("fast" is vague but not incoherent) - Formatting inconsistencies (header levels, indentation, markdown style) -- Document organization opinions when the structure works without self-contradiction +- Document organization opinions when the structure works without self-contradiction (exception: ungrouped requirements spanning multiple distinct concerns -- that's a structural issue, not a style preference) - Explicitly deferred content ("TBD," "out of scope," "Phase 2") - Terms the audience would understand without formal definition diff --git a/plugins/compound-engineering/skills/ce-brainstorm/SKILL.md b/plugins/compound-engineering/skills/ce-brainstorm/SKILL.md index 7565a07..5e414c9 100644 --- a/plugins/compound-engineering/skills/ce-brainstorm/SKILL.md +++ b/plugins/compound-engineering/skills/ce-brainstorm/SKILL.md @@ -186,8 +186,13 @@ topic: [Who is affected, what is changing, and why it matters] ## Requirements -- R1. [Concrete user-facing behavior or requirement] -- R2. [Concrete user-facing behavior or requirement] + +**[Group Header]** +- R1. [Concrete requirement in this group] +- R2. [Concrete requirement in this group] + +**[Group Header]** +- R3. [Concrete requirement in this group] ## Success Criteria - [How we will know this solved the right problem] @@ -221,6 +226,8 @@ For **Lightweight** brainstorms, keep the document compact. Skip document creati For very small requirements docs with only 1-3 simple requirements, plain bullet requirements are acceptable. For **Standard** and **Deep** requirements docs, use stable IDs like `R1`, `R2`, `R3` so planning and later review can refer to them unambiguously. +When requirements span multiple distinct concerns, group them under bold topic headers within the Requirements section. The trigger for grouping is distinct logical areas, not item count — even four requirements benefit from headers if they cover three different topics. Group by logical theme (e.g., "Packaging", "Migration and Compatibility", "Contributor Workflow"), not by the order they were discussed. Requirements keep their original stable IDs — numbering does not restart per group. A requirement belongs to whichever group it fits best; do not duplicate it across groups. Skip grouping only when all requirements are about the same thing. + When the work is simple, combine sections rather than padding them. A short requirements document is better than a bloated one. Before finalizing, check: diff --git a/plugins/compound-engineering/skills/document-review/references/findings-schema.json b/plugins/compound-engineering/skills/document-review/references/findings-schema.json index 5ec70c3..52515e4 100644 --- a/plugins/compound-engineering/skills/document-review/references/findings-schema.json +++ b/plugins/compound-engineering/skills/document-review/references/findings-schema.json @@ -98,7 +98,7 @@ }, "autofix_classes": { "auto": "Local, deterministic document fix: terminology consistency, formatting, cross-reference correction, completeness corrections (wrong counts, missing list entries, undefined values where the correct value is verifiable from elsewhere in the document). Must be unambiguous.", - "batch_confirm": "Obvious fix with a clear correct answer, but touches document meaning enough to warrant user awareness. Grouped with other batch_confirm findings for a single approval rather than individual review. Examples: adding a missing implementation step that is mechanically implied, updating a section summary to reflect its own contents.", + "batch_confirm": "Obvious fix with a clear correct answer, but requires authoring new content where exact wording needs verification. Grouped with other batch_confirm findings for a single approval rather than individual review. Examples: adding a missing implementation step that is mechanically implied, rewording a section to resolve an ambiguity. Note: fixes that are deterministically derivable from existing document content (updating a summary to match its own list, correcting a count, adding group headers to requirements) belong in auto, not here.", "present": "Requires individual user judgment -- strategic questions, design tradeoffs, meaning-changing fixes, or findings where reasonable people could disagree on the right action." }, "finding_types": {