delivery-friction-analyzer 0.1.0 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 Delivery Friction Analyzer is a product concept for measuring where AI-assisted software delivery still wastes time: review loops, CI churn, scope drift, missing validation, and repeated corrective work after a pull request opens.
 
-The core idea is to use GitHub data as the first durable signal. Pull request diffs, review comments by source, check runs, commits, changed-file spread, file roles, and merge timelines can reveal which repositories, modules, and workflow stages create the most back-and-forth before work becomes mergeable.
+The core idea is to use GitHub data as the first durable signal. Pull request diffs, review comments by source, check runs, commits, change scope, file roles, and merge timelines can reveal which repositories, modules, and workflow stages create the most back-and-forth before work becomes mergeable.
 
 ## Product Direction
 

package/docs/contracts/friction-report.md

@@ -32,7 +32,7 @@ The command reads local `friction-metrics.v1` JSON and writes deterministic `fri
 - `commentSources`: total and source-grouped review comments for Copilot, human, bot, scanner, author replies, and unknown sources.
 - `surfaces`: core, low-signal, generated, support-surface, role, and functional-surface breakdowns.
 - `prClasses`: PR class distribution for the analyzed sample, including PR counts, changed lines, share of PRs, and classification source counts by class.
-- `bottlenecks`: ranked friction patterns with observed data, inferred diagnosis, and suggested action kept as separate fields.
+- `bottlenecks`: ranked friction patterns with observed data, inferred diagnosis, and suggested action kept as separate fields. `bottlenecks[].title` is a reader-facing display label and may change for clarity while stable IDs such as `changed-file-spread` remain unchanged.
 - `bottlenecks[].observedData[]`: representative PR examples with PR identity, score/value, PR class evidence, final/current additions, deletions, changed-file count, and changed-line count.
 - `bottlenecks[].observedData[].validationEvidence`: workflow-run source label, workflow-run coverage, workflow-run conclusions, failed check-run count, failed workflow-run count, and cancelled workflow-run count for representative PR examples.
 - `bottlenecks[].observedData[].reviewEvidence`: review-thread source label, thread counts, resolution/outdated counts, review decision label/source, human reviewer count, human approval / changes-requested booleans, comment-source breakdown, bot comment count, human reviewer comment count, and author reply count for representative PR examples.
@@ -44,21 +44,23 @@ The command reads local `friction-metrics.v1` JSON and writes deterministic `fri
 - `guardrails`: machine-readable checks that the report avoids individual ranking, separates evidence from inference, and does not use an opaque composite score.
 - `followUp`: non-automated future work suggested by the report.
 
-Bottlenecks are ordered by their strongest observed representative metric value, with stable category order used only to break ties. Final/current PR size fields are context for comparing size against friction signals; they only affect ordering for metric families that explicitly measure changed-file spread.
+Bottlenecks are ordered by their strongest observed representative metric value, with stable category order used only to break ties. Final/current PR size fields are context for comparing displayed examples against friction signals; they are not separate ordering inputs. The internal `changedFileSpread` / `changed-file-spread` signal remains the stable contract name for the metric that sums core files touched, directories touched, and functional surfaces touched. It is not a changed-line-count metric.
 
 ## Markdown Output
 
 The Markdown renderer presents the same report data for human review:
 
-- executive summary totals in a table;
 - explicit analysis filter labels when downstream artifacts were generated from a filtered PR class sample;
+- executive summary totals plus top findings, triggered recommendation categories, and filter status in a table;
+- a top-of-report focus snapshot that names focus areas, action categories, evidence reviewed, and confidence caveats before detailed bottlenecks;
+- a compact recommendation-category snapshot before detailed bottlenecks, with the full category reference retained later in the report;
 - a short "How To Read This Report" guide that distinguishes observed evidence, interpretation, recommendations, and caveats;
 - evidence-quality and coverage tables before detailed recommendations;
 - key findings that highlight top bottlenecks, strongest displayed signal, outlier caveats, PR class caveats, and coverage caveats;
 - a PR class context table that shows analyzed PR counts, changed lines, sample share, and classification sources by class;
 - a top-level shared-signal interpretation callout when multiple displayed bottlenecks share a ranking key or representative PR evidence;
 - outlier and sensitivity analysis when displayed examples are dominated by one PR;
-- a prioritization explanation that describes strongest-signal ordering and how PR size is used as context;
+- a prioritization explanation that describes strongest-signal ordering and how PR size is used as context, using reader-facing change-scope language while mapping back to the internal changed-file-spread signal when needed;
 - ranked bottlenecks with representative PR examples rendered as compact PR-size tables;
 - validation, review, and source-label evidence for each representative PR example rendered as plain Markdown detail lists;
 - separately labeled inferred diagnosis, suggested action, and confidence/caveat blocks for each bottleneck;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "delivery-friction-analyzer",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "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 — 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.
+- Why it matters: Maintainers can see what deserves attention, why the report is confident or caveated, and which action themes apply without reading through the full ranked bottleneck details first.
+- Who is affected: Maintainers and contributors reviewing generated friction reports.
+- Action needed: None.
+- PR: https://github.com/hannasdev/delivery-friction-analyzer/pull/30
+
 ### 2026-06-14 — NPM Release Automation
 
 - What changed: The package is prepared for public npm distribution with CLI metadata, a tight npm package allowlist, CI package dry-runs, automated conventional-commit versioning, GitHub release creation, and tag-triggered npm publishing.

package/src/report/evidence-artifacts.js

@@ -375,7 +375,7 @@ export function renderRepositoryFrictionMethodology({
     "",
     "## Scores And Rankings",
     "",
-    "The report ranks bottlenecks by transparent component metrics from `friction-metrics.v1`: review churn, changed-file spread, validation gap, planning gap, review surprise, and fix amplification. These are not an opaque composite score, and they are not individual contributor or reviewer rankings.",
+    "The report ranks bottlenecks by transparent component metrics from `friction-metrics.v1`: review churn, change scope (the internal changed-file-spread signal: core files touched plus directories touched plus functional surfaces touched), validation gap, planning gap, review surprise, and fix amplification. These are not an opaque composite score, and they are not individual contributor or reviewer rankings.",
     "",
     "## Coverage And Limitations",
     "",

package/src/report/friction-report.js

@@ -54,7 +54,7 @@ const RECOMMENDATION_CATEGORY_LABELS = new Map(
 
 const RANKING_SIGNAL_LABELS = new Map([
   ["reviewChurn", "review churn"],
-  ["changedFileSpread", "changed-file spread"],
+  ["changedFileSpread", "change scope"],
   ["validationGap", "validation gap"],
   ["planningGap", "planning gap"],
   ["reviewSurprise", "review surprise"],
@@ -74,7 +74,7 @@ const BOTTLENECK_DEFINITIONS = [
   {
     id: "changed-file-spread",
     rankingKey: "changedFileSpread",
-    title: "Changed-file spread",
+    title: "Change scope",
     metricLabel: "spread score",
     recommendationCategory: "smaller_milestones",
     action: "Break broad changes into smaller milestones when core files, directories, or surfaces spread out.",
@@ -950,6 +950,30 @@ function renderRecommendationCategories(categories) {
   );
 }
 
+function triggeredRecommendationCategories(categories) {
+  return (categories ?? []).filter(category => Number(category.triggeredBottlenecks ?? 0) > 0);
+}
+
+function renderRecommendationCategorySnapshot(categories) {
+  const triggered = triggeredRecommendationCategories(categories);
+  if (!triggered.length) {
+    return "No recommendation categories were triggered by the displayed bottleneck evidence.";
+  }
+
+  return renderMarkdownTable(
+    ["Category", "Triggered bottlenecks"],
+    triggered.map(category => [
+      category.label,
+      category.triggeredBottlenecks,
+    ]),
+  );
+}
+
+function formatCount(value, singular, plural = `${singular}s`) {
+  const count = Number(value ?? 0);
+  return `${count} ${count === 1 ? singular : plural}`;
+}
+
 function renderInterpretationAndRecommendation(bottleneck) {
   return renderMarkdownTable(
     ["Field", "Value"],
@@ -963,14 +987,38 @@ function renderInterpretationAndRecommendation(bottleneck) {
 function renderPriorityExplanation() {
   return renderList([
     "Bottlenecks are ordered by their strongest displayed representative score, not by an opaque composite priority score.",
-    "Each score comes from one metric family, such as review-loop drag, validation failures, changed-file spread, planning signals, review surprise, or post-review commits.",
+    "Each score comes from one metric family, such as review-loop drag, validation failures, change scope, planning signals, review surprise, or post-review commits.",
+    "Change scope is the internal changed-file-spread signal: core files touched plus directories touched plus functional surfaces touched. It is not a line-count metric.",
     "PR size columns show final/current additions, deletions, changed files, and changed lines so readers can compare size against the detected friction signals.",
-    "PR size is context for interpretation; it only affects ordering when the bottleneck metric itself is about changed-file spread.",
+    "PR size columns are context for interpreting displayed examples; bottleneck ordering uses each metric family's representative score and stable tie-breaks, not the PR size columns.",
     "Coverage caveats and outlier dominance should be considered before treating the first bottleneck as the most important repository problem.",
   ]);
 }
 
-function renderSummaryTable(summary) {
+function topBottleneckLabels(report) {
+  const bottlenecksById = new Map((report.bottlenecks ?? []).map(bottleneck => [bottleneck.id, bottleneck]));
+  const ids = report.summary?.topBottleneckIds ?? [];
+  const labels = ids
+    .map(id => bottlenecksById.get(id)?.title ?? id)
+    .filter(Boolean);
+  return labels.length ? labels.join(", ") : "none";
+}
+
+function triggeredCategoryLabels(report) {
+  const categories = triggeredRecommendationCategories(report.recommendationCategories);
+  return categories.length
+    ? categories.map(category => `${category.label} (${category.triggeredBottlenecks})`).join(", ")
+    : "none";
+}
+
+function formatAnalysisFilterStatus(report) {
+  const filter = report.analysisFilter;
+  if (!filter?.excludedPrClasses?.length) return "none";
+  return `excluded PR class(es): ${filter.excludedPrClasses.join(", ")}; filtered sample ${filter.filteredPullRequests} of ${formatCount(filter.originalPullRequests, "collected PR")}`;
+}
+
+function renderSummaryTable(report) {
+  const summary = report.summary ?? {};
   return renderMarkdownTable(
     ["Metric", "Value"],
     [
@@ -981,7 +1029,9 @@ function renderSummaryTable(summary) {
       ["Review threads", summary.reviewThreads],
       ["Failed checks", summary.failedChecks ?? 0],
       ["Cancelled workflow runs", summary.cancelledWorkflowRuns ?? 0],
-      ["Top bottlenecks", (summary.topBottleneckIds ?? []).join(", ") || "none"],
+      ["Top findings", topBottleneckLabels(report)],
+      ["Triggered recommendation categories", triggeredCategoryLabels(report)],
+      ["Analysis filter", formatAnalysisFilterStatus(report)],
     ],
   );
 }
@@ -998,7 +1048,7 @@ function renderCoverageSummary(coverage) {
 }
 
 function renderKeyFindings(report) {
-  const topBottlenecks = (report.summary.topBottleneckIds ?? []).join(", ") || "none";
+  const topBottlenecks = topBottleneckLabels(report);
   const strongest = report.bottlenecks?.[0];
   const dominanceCallouts = (report.bottlenecks ?? [])
     .filter(bottleneck => bottleneck.dominance?.status === "single_pr_dominates")
@@ -1025,6 +1075,50 @@ function renderKeyFindings(report) {
   ]);
 }
 
+function summarizeFocusCaveats(report) {
+  const caveats = [];
+  const coverageNotes = report.coverage?.notes ?? [];
+  const dominantPrs = (report.bottlenecks ?? [])
+    .filter(bottleneck => bottleneck.dominance?.status === "single_pr_dominates");
+  const dominantClasses = (report.bottlenecks ?? [])
+    .filter(bottleneck => bottleneck.classDominance?.status === "single_class_dominates");
+
+  if (coverageNotes.length) caveats.push(formatCount(coverageNotes.length, "coverage caveat"));
+  if (dominantPrs.length) caveats.push(formatCount(dominantPrs.length, "outlier caveat"));
+  if (dominantClasses.length) caveats.push(formatCount(dominantClasses.length, "PR class caveat"));
+  if (!caveats.length) return "No early confidence caveats were recorded for the displayed evidence.";
+
+  return `${caveats.join(", ")}. Read the evidence and caveat sections before generalizing.`;
+}
+
+function renderFocusSnapshot(report) {
+  const summary = report.summary ?? {};
+  const categories = triggeredCategoryLabels(report);
+  const evidenceReviewed = [
+    formatCount(summary.pullRequests, "PR"),
+    formatCount(summary.changedLines, "changed line"),
+    formatCount(summary.nonGeneratedChangedLines, "non-generated changed line"),
+    formatCount(summary.reviewComments, "review comment"),
+    formatCount(summary.reviewThreads, "review thread"),
+    formatCount(summary.failedChecks, "failed check"),
+    formatCount(summary.cancelledWorkflowRuns, "cancelled workflow run"),
+  ].join(", ");
+  const firstInspection = (report.bottlenecks ?? [])
+    .slice(0, 3)
+    .map(bottleneck => bottleneck.title)
+    .join(", ") || "No detailed bottleneck evidence was available.";
+
+  return renderMarkdownTable(
+    ["Question", "Answer"],
+    [
+      ["Focus first", firstInspection],
+      ["Action categories", categories],
+      ["Evidence reviewed", evidenceReviewed],
+      ["Confidence caveats", summarizeFocusCaveats(report)],
+    ],
+  );
+}
+
 function classDominanceFallback(prClasses) {
   const sampleClasses = (prClasses?.distribution ?? []).filter(entry => entry.pullRequests > 0);
   if (!sampleClasses.length) {
@@ -1189,7 +1283,15 @@ export function renderRepositoryFrictionMarkdown(report) {
     ...analysisFilterLines,
     "## Executive Summary",
     "",
-    renderSummaryTable(report.summary),
+    renderSummaryTable(report),
+    "",
+    "## Focus Snapshot",
+    "",
+    renderFocusSnapshot(report),
+    "",
+    "## Recommendation Category Snapshot",
+    "",
+    renderRecommendationCategorySnapshot(report.recommendationCategories ?? []),
     "",
     "## How To Read This Report",
     "",