delivery-friction-analyzer 0.2.0 → 0.2.1

package/README.md

@@ -73,6 +73,14 @@ Read `friction-report.md` first, then inspect `methodology.md`, the CSV exports,
 
 Ranked bottlenecks are ordered by their strongest displayed representative score, not by an opaque composite priority score. PR size columns show final/current additions, deletions, changed files, and changed lines so maintainers can compare size against review, validation, and planning signals.
 
+### Optional narrative drafting
+
+The generated artifacts are also enough context for an optional local workflow where a separate model drafts a narrative report. Use `friction-report.json` as the structured source of truth, `friction-report.md` as the human-readable source of truth, and the curated CSV exports only as supporting evidence when the draft needs per-PR detail.
+
+When using a model this way, keep the deterministic artifacts authoritative: preserve coverage, outlier, PR-class, and analysis-filter caveats; distinguish observed evidence from inferred diagnosis and suggested action; do not invent missing data; and do not rank individuals. Review any generated prose against the Markdown, JSON, and CSV evidence before sharing it.
+
+No separate model-ready context artifact is required for this workflow. Reconsider a new artifact only if a concrete consumer needs a smaller single-file context, machine-readable prompt packaging, or fields that cannot be represented clearly by `friction-report.json` plus curated CSV evidence.
+
 Known MVP interpretation limits:
 
 - PR-open diff growth is unavailable unless an open-time snapshot or reconstruction exists; the local historical collector does not infer it from merge-time diff data.

package/docs/contracts/friction-report.md

@@ -128,6 +128,29 @@ Minimum CSV column groups:
 
 Empty CSV cells mean unavailable or not applicable. Numeric zero should be used only for observed or computed zero counts. Count columns that depend on optional GitHub coverage should keep source or coverage labels nearby so spreadsheet readers can tell unavailable evidence apart from observed zeroes. CSVs must not include raw comment bodies, raw workflow logs, tokens, secret-bearing environment details, or individual contributor/reviewer rankings.
 
+## Optional Downstream Narrative Drafting
+
+The existing `friction-report.json` artifact plus the curated CSV exports are sufficient context for an optional local workflow where a separate model drafts a narrative summary. M2 does not justify a new `report-context.json`, CLI flag, fixture output, or artifact write path.
+
+Use `friction-report.json` as the structured source of truth for report identity, summary totals, coverage, PR class context, ranked bottlenecks, shared signals, sensitivity, recommendation categories, guardrails, and follow-up. Use `friction-report.md` as the human-readable source-of-truth report. Use CSV exports as supporting evidence trails when a draft needs per-PR or source-level detail:
+
+- `pr-metrics.csv` for analyzed PR rows, class labels, review/validation counts, and ranking scores.
+- `bottleneck-examples.csv` for representative examples tied to bottleneck identity, recommendation category, evidence sources, dominance, and score/value.
+- `comment-sources.csv` for source-grouped comment totals and classification flags.
+- `collection-coverage.csv` for API-family coverage, attempts, source labels, diagnostics, and downstream impact.
+
+A guarded narrative-drafting workflow should:
+
+1. Run full live analysis with CSV exports enabled unless the user intentionally does not want spreadsheet-friendly evidence files.
+2. Review `friction-report.md` first to understand the deterministic report and caveats.
+3. Provide the model `friction-report.json` plus only the CSV rows or excerpts needed for the requested narrative.
+4. Instruct the model to treat deterministic artifacts as authoritative, preserve coverage/outlier/class/filter caveats, distinguish observed evidence from inferred diagnosis and suggested action, avoid inventing missing data, and avoid ranking individuals.
+5. Review the generated narrative against `friction-report.md`, `friction-report.json`, and the CSV evidence before sharing it.
+
+Model-generated prose is a draft convenience, not a replacement for the deterministic Markdown, JSON, methodology, or CSV artifacts. The artifact sensitivity guidance applies to any prompt, model context, draft, or copied excerpt derived from these files.
+
+A future model-ready context artifact should be reconsidered only if a concrete consumer needs a smaller single-file context, machine-readable prompt packaging, or fields that cannot be represented clearly by `friction-report.json` plus curated CSV evidence without forcing raw CSV interpretation.
+
 ## Guardrails
 
 Reports present repository-level patterns, representative PR examples, and file surface evidence. They must keep observed data, inferred diagnosis, and suggested action distinct, and they must not rank contributors or reviewers.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "delivery-friction-analyzer",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Local GitHub pull request analytics for delivery friction reports.",
   "license": "MIT",
   "type": "module",

package/release-log.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+### 2026-06-15 — Optional Narrative Drafting Guidance
+
+- What changed: The README and friction report contract now document how to use `friction-report.json` with curated CSV evidence as sufficient context for optional downstream narrative drafting, without adding a separate model-ready artifact.
+- Why it matters: Maintainers can draft narrative summaries from existing analyzer outputs while keeping deterministic reports authoritative and avoiding extra artifact surface area.
+- Who is affected: Maintainers and contributors using generated friction reports as input for narrative summaries.
+- Action needed: None.
+- PR: https://github.com/hannasdev/delivery-friction-analyzer/pull/31
+
 ### 2026-06-15 — First-Glance Report Opening
 
 - What changed: Friction reports now open with a focus snapshot, early recommendation-category summary, reviewed-evidence counts, and confidence caveats before detailed bottleneck evidence.