Epic: work-package planning-artifact verbosity reduction

[m2ux]

Overview

Epic tracking the reduction of work-package planning-artifact verbosity and cross-document redundancy, from a review of three recent planning folders cross-referenced against the workflow templates/techniques and the artifact-management docs (see References):

• Each run produces 17–22 markdown artifacts (~1,200–1,850 lines); ~14–18% is near-identical cross-document restatement, plus ~12–15% within-document padding in the prose-heavy artifacts.
• Worst cases: the problem statement in up to four documents per run, research reproduced verbatim in the plan, consolidated-review duplicating code-review findings wholesale, deferred items scattered across four documents with no single register.
• The style rules already forbid all of this (state-once-per-artifact, single-source-and-link, exception-only reporting) — the templates structurally mandate the duplication and nothing enforces the rules. Root causes below; the backlog is the work list.

Target: 30–40% fewer markdown lines per run and ~1/3 fewer prose documents, with no information loss (agent state persists in structured form).

Root causes

• RC1 — Templates structurally mandate the overlap. Problem Statement is prescribed by three templates (wp-plan, requirements-elicitation, design-framework), Success Criteria by four, Assumptions/Design Decisions/Risks by three each, Scope by two. Even a perfectly rule-compliant worker produces the redundancy.
• RC2 — The plan template invites research leakage. wp-plan.md's "Key Findings Summary" is a restatement slot; workers fill it with copied findings despite the adjacent single-source-and-link rule.
• RC3 — Prose rules have no structural enforcement. Nothing at the finalize boundary checks state-once/single-source conformance, so compliance decays per-worker (same failure class as Review mode: posted consolidated review can diverge from the Consolidated Review Format (no conformance gate at the posting boundary) #197/Review mode: enforce canonical Consolidated Review Format before posting (add conformance gate) #218, which got a conformance gate).
• RC4 — Audience is ambiguous, so format doesn't follow function. Machine state lives in session.json (the only thing re-read on resume); artifacts nominally serve human operators. In practice the set splits three ways with no declared distinction: human-primary (design-philosophy, kb-research, architecture-summary, strategic-review, COMPLETE, README, portfolio-*), agent-primary ID-bearing state (assumptions-log, findings-classification, change-block-index, provenance-log, debt-ledger), and hybrid (plan, test-plan). The agent-primary artifacts are dense tables no human reads linearly, yet they are serialized as prose markdown interleaved with the human documents. The technique protocol's #### artifact output metadata carries only a filename — no audience/format axis.

Backlog

Cluster groups items by natural implementation order (1–5; within a PR, work the clusters in ascending order). PR is the strict allocation — only two PRs, split at the one hard boundary (server code vs workflows corpus). Server / Workflows mark which repo surface each item touches. V5 depends on V4 and V3.

#	Cluster	PR	Server	Workflows	Change	Removes	Effort	Risk
V1	1	2		✅	Finalize-boundary conformance gate (sibling of verify-readme-conforms): canonical-home sections not duplicated, no restatement in link-only slots, null sections omitted; per-template line budgets where a structural check is impractical	RC3	S	Low
V2	1	2		✅	Replace wp-plan.md's "Key Findings Summary" with a link-only Inputs list (one line per consumed artifact, anchors permitted)	RC2	S	None
V3	3	2		✅	Canonical-home map: each fact category gets one home artifact; strip duplicated sections from all other templates, replace with one-line link slots; update the coupled technique operations that reference template sections by name	RC1	M	Medium
V4	2	1	✅		Audience attribute (human | agent) on technique output declarations: protocol spec + parser/schema validation, projection into the worker-delivered technique bundle (format known at write time), get_activity artifacts-contract carry-through, JSON format conventions under the artifactPrefix rule, corpus lint coverage	RC4 (enabler)	M	Low
V5	4	2		✅	Convert agent-state artifacts to structured data using V4: assumptions-log reconciliation state, findings-classification routing, change-block-index, provenance-log, debt-ledger	RC4	M	Medium
V6	3	2		✅	Review-cluster consolidation: consolidated-review references findings by ID + disposition only; merge small advisory artifacts (structural-analysis, lean-coding-audit, manual-diff-review, findings-classification) into code-review / strategic-review; single deferred-items register all other documents link to	RC1	M	Low
V7	4	2		✅	Version bump + reference sweep: technique ## Outputs blocks and downstream references to old filenames (inputs of later techniques, README artifact lists, complete-wp.md link tables, retro tooling greps)	—	S	Low
V8	5	2		✅	Codify the anti-patterns into the workflow-design workflow so new workflows can't reintroduce them: template-mandated section duplication, restatement slots, style rules without enforcement, undeclared artifact audience — added to its authoring guidance/review checklist, plus corpus lint where mechanically checkable (e.g. the same prescribed section heading across multiple templates of one workflow)	RC1–RC4 recurrence	S	None

Implementation clusters & PR allocation

Clusters express the natural implementation order and change groupings — an agent implementing within a PR should work them in ascending cluster order:

• Cluster 1 — quick wins: V1 + V2. Small, independent, immediately valuable; V1's gate also protects the later restructure from regression.
• Cluster 2 — audience machinery: V4. Server-side; no corpus consumer yet at this point (same pattern as hybrid bundling in Epic: schema/technique/disclosure review backlog (2026-07-03) #166). Parallelizable with clusters 1 and 3.
• Cluster 3 — corpus restructure: V3 + V6. One coordinated pass over the work-package templates and their coupled technique operations — grouped because they rewrite the same files. Affected resources: wp-plan.md, design-framework.md, requirements-elicitation.md, implementation-analysis.md, knowledge-base-research.md, test-plan.md, assumptions-review.md, strategic-review.md, architecture-summary.md, complete-wp.md, readme.md, review-mode resources. Affected techniques: plan-prepare/plan.md, research/document.md, implementation-analysis/document.md, requirements-elicitation/create-document.md, design-philosophy/document.md, review-assumptions/*, strategic-review/document-findings.md, finalize-documentation/*, manage-artifacts/*.
• Cluster 4 — state extraction & close-out (needs 2 + 3): V5 + V7. Converts the agent-state artifacts to structured outputs (consuming cluster 2's machinery on cluster 3's restructured corpus); the version bump and filename-reference sweep ride the same pass since the sweep must reflect the final artifact set.
• Cluster 5 — design-time prevention (last): V8. Touches workflow-design rather than work-package; distills what clusters 1–4 fixed into authoring guidance and lint, so it lands once those are settled.

Strict PR allocation — two PRs, split only at the hard repo boundary (server code on main vs workflows corpus); do not split further:

• PR 1 (server): cluster 2 (V4). Merges first.
• PR 2 (workflows corpus): clusters 1, 3, 4, 5 (V1–V3, V5–V8), implemented as staged commits in that cluster order.

Sessions started under the old version complete under it (resume loads workflowVersion from session.json), so no migration of existing planning folders.

Tracking

PR 1 (server) — cluster 2 — delivered in #227

• V4 — audience attribute end-to-end (spec, validation, worker-bundle projection, contract, JSON conventions, lint) — feat: audience attribute (human | agent) on technique output declarations (#224 V4) #227

PR 2 (workflows corpus) — clusters 1, 3, 4, 5 in order — delivered in #226

• V1 — finalize conformance gate (cluster 1) — feat(work-package): planning-artifact verbosity reduction - epic #224 PR 2 (V1-V3, V6-V8) #226
• V2 — wp-plan link-only inputs (cluster 1) — feat(work-package): planning-artifact verbosity reduction - epic #224 PR 2 (V1-V3, V6-V8) #226
• V3 — canonical-home template/technique restructure (cluster 3) — feat(work-package): planning-artifact verbosity reduction - epic #224 PR 2 (V1-V3, V6-V8) #226
• V6 — review-cluster consolidation + deferred-items register (cluster 3) — feat(work-package): planning-artifact verbosity reduction - epic #224 PR 2 (V1-V3, V6-V8) #226
• V5 — agent-state artifacts → structured data (cluster 4) — deferred pending V4 (PR 1); its share of the V7 sweep rides with it
• V7 — version bump + reference sweep (cluster 4) — feat(work-package): planning-artifact verbosity reduction - epic #224 PR 2 (V1-V3, V6-V8) #226 (remainder for V5's artifacts follows V5)
• V8 — anti-patterns codified into workflow-design (cluster 5) — feat(work-package): planning-artifact verbosity reduction - epic #224 PR 2 (V1-V3, V6-V8) #226 (AP-86–89)

Non-goals / constraints

• No change to session.json ownership or the resume model — machine state remains server-managed; this epic only relocates workflow-visible working state that currently masquerades as prose documents.
• README.md progress-tracking mandate stays as-is (the docs explicitly designate it as the human operator's entry point).
• Traceability must not regress: assumption/task/test/gap ID binding survives, just in structured form rather than markdown tables where the audience is agent-only.

References

Evidence base for the numbers above (redundancy matrices, template section-overlap matrix, per-artifact audience judgments, producer→consumer graph):

• Planning folders reviewed: 2026-07-08-node-expose-ledger-events, 2026-07-03-midnight-node-issue-498-cip19-cardano-reward-address-validation, 2026-07-11-review-midnight-node-pr-1800
• Workflow definition: work-package on the workflows branch — templates in resources/, style ruleset in techniques/manage-artifacts/
• Server docs: artifact_management_model.md, state_management_model.md, technique-protocol-specification.md, resource_resolution_model.md

🤖 Generated with Claude Code

[m2ux]

PR 2 (workflows corpus) is up: #226 — V1, V2, V3, V6, V7, V8 as four staged commits in cluster order (work-package 3.29.0, workflow-design 1.8.0 with AP-86–89).

Scope note: V5 is deferred until PR 1 (V4 audience machinery) exists, since it consumes that server surface; its share of the V7 filename sweep rides with it. Design decisions (gate placement at strategic-review, prism/ponytail findings-destination input, canonical-home map) are recorded in the design session artifacts.

Post-merge follow-up: server-repo binding-fidelity baseline regen (262 → ~256), tracked in #226's description.

🤖 Generated with Claude Code