delivery-friction-analyzer 0.8.0 → 0.9.0

package/docs/contracts/friction-report.md

@@ -1,6 +1,6 @@
 # Friction Report Contract
 
-Milestone 3 introduces `friction-report.v1`, a deterministic report generated from a `friction-metrics.v1` repository metrics summary. The report layer does not fetch GitHub data, mutate repositories, rank individuals, or depend on services beyond the data collection path that produced the metrics summary.
+Milestone 3 introduced `friction-report.v1`, a deterministic report generated from a `friction-metrics.v1` repository metrics summary. Milestone 4 adds Markdown and methodology profile suggestions without adding report JSON fields. The report layer does not fetch GitHub data, mutate repositories, rank individuals, or depend on services beyond the data collection path that produced the metrics summary.
 
 ## Outputs
 
@@ -60,6 +60,7 @@ The Markdown renderer presents the same report data for human review:
 - 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;
+- profile suggestions when fallback `unknown` PR classes or unknown file role/surface evidence cross deterministic thresholds;
 - 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, using reader-facing change-scope language while mapping back to the internal changed-file-spread signal when needed;
@@ -75,6 +76,7 @@ The Markdown renderer presents the same report data for human review:
 
 Markdown output should not include individual contributor or reviewer rankings.
 Status labels are Markdown presentation helpers, not `friction-report.v1` fields. They should preserve the underlying source labels and counts rather than replacing auditable evidence.
+Profile suggestions are also presentation helpers, not `friction-report.v1` fields. They are derived from existing PR class and file-surface evidence, appear at most once per suggestion category, and do not change scores, rankings, CSV exports, filtering, or PR class matching. Because the report JSON does not carry repository-profile rule inventory, all analyzed PRs using fallback `unknown` PR class evidence is the renderer's small-sample proxy for no configured PR class rule producing usable classification evidence.
 
 ## Recommendation Boundaries
 
@@ -109,6 +111,7 @@ Full live analysis writes `methodology.md` as a hybrid artifact: stable explanat
 - target repository and report/metric versions;
 - profile path when available;
 - configured workflow context when supplied by the repository profile, labeled as user-configured context rather than observed GitHub evidence;
+- profile suggestions when PR class or file/path profile evidence crosses deterministic fallback thresholds, or an explicit no-threshold note when none were triggered;
 - requested and collected PR counts;
 - collection coverage status and API-family diagnostics;
 - scoring, ranking, dominance, sensitivity, and limitation explanations;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "delivery-friction-analyzer",
-  "version": "0.8.0",
+  "version": "0.9.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-20 — Profile Improvement Suggestions
+
+- What changed: Markdown friction reports and methodology now suggest PR class or file/path profile improvements when fallback `unknown` evidence dominates the analyzed sample.
+- Why it matters: Maintainers can see where repository profile rules would improve interpretation without treating the suggestions as score changes or required fixes.
+- Who is affected: Maintainers and contributors reviewing generated reports or authoring repository profiles.
+- Action needed: Optional; add or refine profile rules when the suggestions match repository conventions.
+- PR: https://github.com/hannasdev/delivery-friction-analyzer/pull/45
+
 ### 2026-06-20 — Report Evidence Status Tables
 
 - What changed: Markdown friction reports now show representative validation, review, and source-label evidence in compact tables with text status labels for observed, partial, unavailable, configured, warning, and healthy states.

package/src/report/evidence-artifacts.js

@@ -2,6 +2,7 @@ import {
   CONFIGURED_WORKFLOW_NOTE,
   configuredWorkflowEntries,
   hasConfiguredWorkflowContext,
+  profileSuggestions,
 } from "./friction-report.js";
 
 const BOT_OR_SCANNER_SOURCES = new Set([
@@ -357,6 +358,30 @@ function formatConfiguredWorkflowContext(report) {
   ];
 }
 
+function formatProfileSuggestions(report) {
+  const suggestions = profileSuggestions(report);
+  if (!suggestions.length) {
+    return [
+      "## Profile Suggestions",
+      "",
+      "- No profile suggestion thresholds were triggered by this report's PR class, role, or functional-surface evidence.",
+      "",
+    ];
+  }
+
+  return [
+    "## Profile Suggestions",
+    "",
+    "Profile suggestions are optional interpretation improvements derived from existing report evidence. They do not change scores, rankings, CSV exports, or JSON report fields.",
+    "",
+    ...suggestions.map(suggestion => [
+      `- ${suggestion.area}: ${suggestion.evidence}`,
+      `  Suggested next step: ${suggestion.suggestion}`,
+    ].join("\n")),
+    "",
+  ];
+}
+
 export function renderRepositoryFrictionMethodology({
   report,
   sourceBundle,
@@ -394,6 +419,7 @@ export function renderRepositoryFrictionMethodology({
     "",
     "The repository profile maps file paths to categories, roles, and functional surfaces. Those classifications drive non-generated changed-line counts, support-surface summaries, planning-document signals, and low-signal weighting.",
     "",
+    ...formatProfileSuggestions(report),
     ...formatConfiguredWorkflowContext(report),
     "## Scores And Rankings",
     "",

package/src/report/friction-report.js

@@ -83,6 +83,12 @@ const WORKFLOW_CONTEXT_VALUE_LABELS = new Map([
 
 export const CONFIGURED_WORKFLOW_NOTE = "Configured workflow context comes from the repository profile. It is user-configured context, not observed GitHub evidence, and it does not change scores, rankings, CSV exports, or PR class matching.";
 
+const PROFILE_SUGGESTION_THRESHOLDS = {
+  minimumPrClassSample: 3,
+  unknownPrClassShare: 0.8,
+  unknownFileShare: 0.25,
+};
+
 const BOTTLENECK_DEFINITIONS = [
   {
     id: "review-churn",
@@ -585,6 +591,61 @@ function summarizeRecommendationCategories(bottlenecks) {
   }));
 }
 
+function entryValue(entries = [], name) {
+  return Number((entries ?? []).find(entry => entry.name === name)?.value ?? 0);
+}
+
+function classSourceValue(entry = {}, source) {
+  return entryValue(entry.classificationSources, source);
+}
+
+export function profileSuggestions(report = {}) {
+  const suggestions = [];
+  const summary = report.summary ?? {};
+  const prClasses = report.prClasses ?? {};
+  const classDistribution = prClasses.distribution ?? [];
+  const totalPullRequests = Number(prClasses.totalPullRequests ?? summary.pullRequests ?? 0);
+  const unknownClass = classDistribution.find(entry => entry.class === "unknown");
+  const unknownClassPullRequests = Number(unknownClass?.pullRequests ?? 0);
+  const fallbackUnknownPullRequests = classSourceValue(unknownClass, "fallback_rule");
+  const fallbackUnknownClassShare = totalPullRequests > 0
+    ? fallbackUnknownPullRequests / totalPullRequests
+    : 0;
+  const everyPrFallbackUnknown = totalPullRequests > 0
+    && unknownClassPullRequests === totalPullRequests
+    && fallbackUnknownPullRequests === unknownClassPullRequests;
+
+  if ((totalPullRequests >= PROFILE_SUGGESTION_THRESHOLDS.minimumPrClassSample
+    && fallbackUnknownClassShare >= PROFILE_SUGGESTION_THRESHOLDS.unknownPrClassShare)
+    || everyPrFallbackUnknown) {
+    suggestions.push({
+      id: "pr-class-rules",
+      area: "PR class rules",
+      evidence: `${fallbackUnknownPullRequests} of ${totalPullRequests} analyzed PRs (${percentageLabel(fallbackUnknownClassShare)}) use fallback unknown PR class evidence.`,
+      suggestion: "Add or refine repository-profile PR class title rules, or rerun interactive setup to add the Conventional Commit preset when it matches the repository.",
+    });
+  }
+
+  const nonGeneratedChangedLines = Number(summary.nonGeneratedChangedLines ?? 0);
+  const surfaces = report.surfaces ?? {};
+  const unknownRoleLines = entryValue(surfaces.byRole, "unknown");
+  const unknownSurfaceLines = entryValue(surfaces.byFunctionalSurface, "unknown");
+  const unknownRoleShare = nonGeneratedChangedLines > 0 ? unknownRoleLines / nonGeneratedChangedLines : 0;
+  const unknownSurfaceShare = nonGeneratedChangedLines > 0 ? unknownSurfaceLines / nonGeneratedChangedLines : 0;
+
+  if (unknownRoleShare >= PROFILE_SUGGESTION_THRESHOLDS.unknownFileShare
+    || unknownSurfaceShare >= PROFILE_SUGGESTION_THRESHOLDS.unknownFileShare) {
+    suggestions.push({
+      id: "file-path-rules",
+      area: "File/path rules",
+      evidence: `Unknown role lines: ${unknownRoleLines} of ${nonGeneratedChangedLines} (${percentageLabel(unknownRoleShare)}); unknown functional-surface lines: ${unknownSurfaceLines} of ${nonGeneratedChangedLines} (${percentageLabel(unknownSurfaceShare)}).`,
+      suggestion: "Add repository-profile path rules for high-volume unknown roles or functional surfaces, starting with the directories that account for the most non-generated changed lines.",
+    });
+  }
+
+  return suggestions;
+}
+
 export function normalizeConfiguredWorkflowContext(workflowContext) {
   if (!workflowContext || typeof workflowContext !== "object" || Array.isArray(workflowContext)) {
     return null;
@@ -1294,6 +1355,27 @@ function renderPrClassContext(prClasses) {
   ].join("\n");
 }
 
+function renderProfileSuggestions(report) {
+  const suggestions = profileSuggestions(report);
+  if (!suggestions.length) return "";
+
+  return [
+    "## Profile Suggestions",
+    "",
+    "Optional profile improvements based on this report's existing evidence. These suggestions do not change scores, rankings, CSV exports, or JSON report fields.",
+    "",
+    renderMarkdownTable(
+      ["Profile area", "Evidence", "Suggested next step"],
+      suggestions.map(suggestion => [
+        suggestion.area,
+        suggestion.evidence,
+        suggestion.suggestion,
+      ]),
+    ),
+    "",
+  ].join("\n");
+}
+
 function renderConfiguredWorkflowContext(configuredWorkflow) {
   const entries = configuredWorkflowEntries(configuredWorkflow);
   if (!entries.length) return "";
@@ -1478,6 +1560,7 @@ export function renderRepositoryFrictionMarkdown(report) {
     renderKeyFindings(report),
     "",
     renderPrClassContext(report.prClasses),
+    renderProfileSuggestions(report),
     renderSharedSignalInterpretation(sharedSignals),
     renderSensitivityAnalysis(report.sensitivity),
     "## How Bottlenecks Are Prioritized",
@@ -1532,6 +1615,9 @@ export function renderRepositoryFrictionMarkdown(report) {
     "",
     "- Pull requests are selected upstream by the collection or fixture workflow; this renderer explains the resulting metrics summary.",
     "- File roles and functional surfaces come from repository-profile classification, not from language names alone.",
+    profileSuggestions(report).length
+      ? "- Profile suggestions are optional interpretation improvements derived from existing report evidence; they do not change scores, rankings, CSV exports, or JSON report fields."
+      : "- No profile suggestion thresholds were triggered by this report's PR class, role, or functional-surface evidence.",
     "- Bottlenecks are ranked by their strongest representative observed signal, with stable category order only used to break ties.",
     "- Recommendations are inferred from transparent component evidence and representative PR examples; they are not automated changes.",
     "- Missing or partial GitHub data remains visible in coverage tables rather than being inferred from unrelated fields.",