Cutting bloat in document-producing agents (BRD/PRD/ADR Builders and more)

[Raymond Nassar (raymond-nassar)]

Cutting bloat in document-producing agents (BRD/PRD Builder)

Problem: Document-producing agents output long, redundant docs. Same content repeats across problem/value/exec-summary, stakeholder/persona/role tables, architecture prose+diagram+table, risks/dependencies, etc.

Proposal: Generalize the PRD Builder prompt into a doc-type-agnostic pattern. Tested on a customer PRD; sharing for hve-core.

Changes

• Configurable inputs: docType + targetReduction — one prompt, many doc shapes.
• 5 universal operating principles (applied before type-specific logic):
  1. Single source of truth per fact
  2. Tables over prose
  3. Prose budget per section
  4. Testable claims only
  5. Engineer/agent-first output
• Redundancy catalog — explicit list of known cross-section overlaps the agent must avoid (not hope to avoid).
• Universal Section Map — 11-section default skeleton when no canonical structure exists.
• Type-Specific Adjustments table — overrides per type: BRD, PRD, ADR, arch review, RAI, meeting notes.
• Prefix taxonomy — extended FR-/NFR-/OQ- with DEC-, RISK-, THREAT-, AC- so downstream agents can parse/reference.
• Verification step — output line count checked against targetReduction.

Open questions

1. Universal-with-overrides vs. one prompt per doc type?
2. Prose budget: lines vs. tokens vs. words — what holds up?
3. Should the redundancy catalog become a shared, versioned list?
4. Adopt the prefix taxonomy as a hve-core convention?

doc-conciseness-review.prompt.md

[eugeneboms]

Thank you for the proposal, Raymond.

A little piece of doubt that I have is with the principal of "Single source of truth per fact". Some sources may be unreliable. Without cross-checking them, it is easy to pick possibly incorrect information and then propagate or multiplicate it. Shall we OK two sources, maybe?

[This is not a hard objection, rather a suggestion]

[Bill Berry (WilliamBerryiii)]

Thanks Raymond Nassar (@raymond-nassar) — this is a real problem and the proposal is a strong start. I want to widen the frame before we lock the shape, because a scan of our own agents shows the pain is bigger (and more interesting) than intra-document verbosity, and one part of the proposed cure is risky exactly where the pain is loudest.

"Bloat" is actually four different problems

#	Driver	Nature	Right lever
1	Multi-audience splitting	Over-production	one audience-aware source, not per-audience copies
2	Scratch/intermediate docs leaking to users	Lifecycle gap	explicit deliverable-vs-scaffolding boundary
3	Standards structure (MADR, NIST, WCAG, STRIDE)	Processing friction, NOT waste	progressive disclosure / review tiers
4	Pipeline & format restatement	Over-production	single source + reference-by-ID + render-on-demand

The current proposal (a post-generation doc-conciseness-review prompt with targetReduction) mostly addresses driver 3's symptom and some intra-doc redundancy. But drivers 1, 2, and 4 are generation-time / orchestration problems — a post-hoc review prompt can compress a finished doc, but it cannot stop an agent from having produced three docs, leaked a scratch doc, or restated the same fact at four pipeline stages.

Scope: decision-grade documents

Proposed membership test: if a doc drives a business/policy/product decision, it must be human-reviewed — and bloat matters because it degrades a reviewer's ability to sign off. That boundary pulls in BRD/PRD, ADR, and the planner assessments (RAI/Security/SSSC/Privacy/Accessibility), and leaves pure execution artifacts (backlog items, RPI scratch) out — except where they're the source of driver 2.

How bad is it (spec-level scan of our repo)

Family	Severity	Why
Planners	Very high	one run emits state.json + multi-phase plan + handoff + dual-format backlog; a single threat/control is restated ~4x (STRIDE table → work item → handoff → backlog item)
Backlog managers	High	each work item authored twice (ADO HTML + GitHub YAML/markdown), disclaimer copied verbatim
BRD / PRD	High	dense, highly sectioned; long-form repetition of context/NFRs/AC/traceability
Design Thinking	Moderate	opt-in expansion (canonical deck, customer cards)
ADR	Low (our exemplar)	already ships a lean Y-statement mode beside full MADR

Caveat: this is design/spec-level, not measured. Numbers need a follow-up pass over real session outputs — flagging that so we don't overclaim.

The collision to be honest about

The planner assessments are where people complain loudest — and their structure is mandated by the compliance frameworks they map to. So targetReduction / line-cutting is most dangerous exactly there: the path of least resistance to hit a line target is to compress the compliance mapping, which is the one thing we must never compress. Conciseness is the wrong instrument for driver 3; processability is the right one.

Proposal: convention-first, prompt-as-backstop

Keep the reusable core, but move the center of gravity to generation time and add a guardrail.

#	Optimization	Targets	Reuses
O1	Single-source work item, render ADO or GitHub on demand	4	backlog-templates shared body
O2	Reference stable threat/control IDs across handoff+backlog instead of restating	4	planner base already mandates stable IDs
O3	Lean review-tier summary + progressive disclosure over the full plan	3 + review	ADR Y-statement precedent
O4	Mark state.json + intermediate phases as internal scaffolding	2	state.json already internal
O5	Audience-aware single source instead of per-audience copies	1	—

Guardrail (non-negotiable): never point line-reduction at standards-mandated / compliance sections. Compress narrative prose; never compliance structure.

Answers to the open questions

1. Universal vs per-type? Neither extreme. A shared convention (operating principles + redundancy catalog + prefix taxonomy) adopted at generation time by each agent, with a shared post-hoc review prompt as a backstop. Per-type specifics stay with each agent/template.
2. Prose budget — lines/tokens/words? Budgets are guardrails for narrative prose only, never for compliance sections. Prefer the structural rule "tables over prose" over raw line targets. Tokens are the cost metric but a poor authoring target (non-deterministic, invisible to humans).
3. Redundancy catalog as a shared versioned list? Yes — and split it into (a) intra-doc overlaps (your list) and (b) cross-artifact/pipeline restatements (the epicenter driver). Version it in-repo.
4. Prefix taxonomy as convention? Strong yes — it's the enabler for O2 (dedup-by-reference) and directly serves downstream agents that parse/reference our docs.

On eugeneboms's "single source of truth" concern

Good catch — and it resolves cleanly by scoping to two different axes:

• Single-source-of-truth applies to internal restatement across our own artifacts (plan vs handoff vs backlog). Safe and valuable — it's our own synthesized content, and single-sourcing makes corrections propagate instead of drift.
• Two-source verification applies to external evidence sourcing — your concern lives here and is right. External facts should still be cross-checked.

Both survive; they just govern different things.

Suggested next step

A small empirical pass: measure line/duplicate-fact counts on 2-3 real planner + backlog outputs to replace "spec-level" with numbers, then pilot O1+O2 on the Security→backlog path (highest driver-4 payoff, lowest effort since stable IDs already exist).

[Bill Berry (WilliamBerryiii)]

As a heads up ... this is on going work right now as we do the skills migration for 4.0. So far we've cut upwards of 20 redundant assets that were being produced that served no human or process handoff. I'll have an update on the total gains soon.