From 5d5ecb60d5ecc9c688b3e4a2b10c068509ab1445 Mon Sep 17 00:00:00 2001 From: Magal Date: Thu, 21 May 2026 06:29:22 -0300 Subject: [PATCH] feat(story-5.3): implement autonomous telemetry deduplication with +1 upvote mechanism - Add Upvotes column and Status field to Feature Requests table - Replace placeholder with full deduplication protocol (7a Read History, 7b Detect Duplicates, 7c Consolidated Ledger) - Add 3 deduplication confinement rules and bounded-read output convention - Address code review: FR ID regex algorithm, intra-sprint dedup, priority elevation --- .../skills/bmad-memtrace-telemetry/SKILL.md | 109 +++++++++++++++--- 1 file changed, 94 insertions(+), 15 deletions(-) diff --git a/.agents/skills/bmad-memtrace-telemetry/SKILL.md b/.agents/skills/bmad-memtrace-telemetry/SKILL.md index 13e2e2c27..f251f7674 100644 --- a/.agents/skills/bmad-memtrace-telemetry/SKILL.md +++ b/.agents/skills/bmad-memtrace-telemetry/SKILL.md @@ -57,7 +57,26 @@ Review your session logs for: For each friction point encountered during the sprint: - Describe the friction (e.g., "query returned too many results before summarization existed") - Note the context (when/where it happened) -- Document the workaround used by the agent +- Document the workaround used by the agent (or "None available — task blocked" if no workaround existed) +- Group related instances of the same underlying cause into a single friction point, reporting the cumulative impact rather than each occurrence separately + +#### Severity Assessment +For each friction point, assess its severity using this scale: + +| Severity | Label | Criteria | +|----------|-------|----------| +| 1 | Cosmetic | Minor inconvenience. No work blocked or delayed. Example: tool name was slightly confusing but still found the right one. | +| 2 | Minor | Slight friction with trivial workaround. Task completed normally. Example: had to retry a query once due to brief timeout. | +| 3 | Moderate | Noticeable delay or rework required. Task still completable within sprint. Example: had to chunk queries manually because batch mode was unavailable. | +| 4 | Severe | Significant rework or alternative approach required. Task was at risk of slipping. Example: stale index forced full re-index before any graph queries could run. | +| 5 | Critical | Task blocked entirely until resolved. Required recovery, fallback, or human intervention. Example: MCP server was unreachable and recovery failed, forcing legacy fallback with human permission. | + +When a friction point could fit two adjacent levels, choose the lower severity. If friction exceeds the Critical definition (e.g., data corruption), score as 5 and note "exceeds scale" in the justification. + +After assigning severity, write a brief justification (1-2 sentences) that references concrete impact on the task. The justification must answer: "What did this friction actually prevent or delay?" If severity is 1 (Cosmetic), justification may state: "No measurable impact — cosmetic only." If tool-call history was unavailable, mark the severity as `~estimated` and note reduced confidence in the section header. + +**Good justification:** "Had to restart the MCP server before blast-radius analysis, delaying the quality gate by 15 minutes. Without the restart, the story could not be verified." (ties to concrete action + delay) +**Bad justification:** "Had a timeout which was a severe issue." (states symptom but doesn't answer *what it prevented or delayed*) ### Step 6: Prepare Comparative Analysis - Contrast graph-based execution (Memtrace) against any legacy text-search heuristics (`grep`, `glob`, `rg`, `find`) that were used @@ -65,10 +84,59 @@ For each friction point encountered during the sprint: - Assess the net impact of structural verification on the sprint's outcomes ### Step 7: Formulate Feature Requests -Based on the friction points identified, draft actionable feature requests for maintainers. Each request should include: -- A clear description of the desired improvement -- Priority (High / Medium / Low) -- Context of the situation that motivated the request + +#### 7a: Read Historical Reports + +Read all prior telemetry reports from `_bmad-output/telemetry/`. Focus specifically on the +"Feature Requests & Feedback" section of each report. Build a consolidated list of all prior +feature requests across all historical reports found. Include only entries with `Status: Active` +— skip Implemented, Rejected, or otherwise retired entries. + +If the `_bmad-output/telemetry/` directory does not exist or is empty, skip to 7c (all +requests are new) — this is normal for the first-ever telemetry run. + +#### 7b: Detect Duplicates + +For each candidate feature request from this sprint, compare against the consolidated list +of prior requests. Two feature requests are HIGHLY SIMILAR (should be merged) when they +satisfy ANY of these criteria: + +| Criterion | Example | +|-----------|---------| +| Same tool or capability being requested | Two reports both request "batch mode for get_impact" | +| Same underlying problem or root cause | Two reports describe timeout issues, even with different wording | +| Same category of improvement | Both request "better error messages for stale index" | +| Semantic overlap (different words, same intent) | "parallel queries" vs "concurrent tool execution" | + +PREFER CONSOLIDATION. When uncertain whether two requests are similar enough to merge, +err on the side of merging them and note in the context field that the request has been +raised in multiple sprints. Only treat a request as truly distinct when it targets a +different tool, a different problem category, or a substantively different improvement. + +#### 7c: Build Consolidated Ledger + +For each entry in your consolidated ledger: +- **Prior request, no new match:** Carry forward with its existing ID, priority, and + upvote count unchanged. +- **Prior request, new match found:** Carry forward with upvote count incremented by +1. + Update the Context field to note the most recent occurrence. +- **New request (no prior match):** Assign a new FR-{n} ID (sequential, continuing from + the highest prior ID found). Set `Status=Active` and upvotes to 1. + +Also draft any genuinely new feature requests from this sprint's friction points using +the same format. Priority should reflect the highest severity of the friction points +that motivated the request. + +**FR ID assignment:** Scan all historical FR tables across prior reports. Extract the +integer `n` from each `FR-{n}` ID using regex `FR-(\d+)`. The new FR ID is `max(n) + 1`. + +**Intra-sprint dedup:** After building the consolidated ledger, run a final consolidation +pass — if two entries within the current sprint's ledger are highly similar (same criteria +as 7b), merge them into a single entry and sum their upvote counts. + +**Priority elevation:** If a carried-forward FR has accumulated upvotes ≥ 3, consider +elevating priority (e.g., L → M). If upvotes ≥ 6, consider elevating again (M → H). +Document any priority changes in the Context field. ## Template Format @@ -120,7 +188,8 @@ Generate the report as a Markdown file following this exact structure. Every sec ## Errors & Failures {Record every Memtrace-related error, timeout, stale index warning, and connection failure - encountered during the sprint.} + encountered during the sprint. The same event may appear in both Errors & Failures (technical + event) and Friction Points (agent experience/impact) with different framing.} ### Connection & Recovery Events @@ -136,11 +205,11 @@ Generate the report as a Markdown file following this exact structure. Every sec ## Friction Points -{Each friction point encountered. Note: future stories may add severity (1-5) and justification fields.} +{Each friction point encountered. Assign a severity score (1-5) and concrete justification. If no friction points were encountered, write "None" rather than omitting the section.} -| Friction | Context | Workaround Used | -|----------|---------|-----------------| -| {description} | {when/where} | {how agent adapted} | +| Friction | Context | Severity (1-5) | Justification | Workaround Used | +|----------|---------|----------------|---------------|-----------------| +| {description} | {when/where} | {3 (Moderate)} | {why this severity — reference concrete task impact} | {how agent adapted — or "None available — task blocked" if no workaround exists} | ## Comparative Analysis: Graph vs Legacy @@ -164,12 +233,12 @@ Generate the report as a Markdown file following this exact structure. Every sec ## Feature Requests & Feedback -{Actionable feature requests or improvement suggestions for the Memtrace maintainers. - Note: future stories will add autonomous +1 upvote deduplication.} +{Cumulative feature requests across ALL sprints. Carry forward only Active prior requests with accumulated + upvote counts. New requests start at 1 upvote with Status=Active. The latest report is the canonical Feature Request ledger.} -| ID | Request | Priority (H/M/L) | Context | -|----|---------|-------------------|---------| -| FR-{n} | {description} | {priority} | {situation that prompted this} | +| ID | Request | Priority (H/M/L) | Status | Upvotes | Context | +|----|---------|-------------------|--------|---------|---------| +| FR-{n} | {description} | {priority} | Active | {count} | {situation that prompted this} | ## Appendix: Complete Tool Catalog Reference @@ -246,6 +315,9 @@ Generate the report as a Markdown file following this exact structure. Every sec - **File collision:** If a file with the exact timestamp already exists, increment the timestamp by 1 second until unique - **Permission failure:** If the agent cannot write to the output directory, output the report to STDOUT with a clear warning and do NOT lose the report data - **Only create the report file** — do NOT create or modify any other files during this workflow +- **Historical report reading:** When reading prior reports for deduplication, target ONLY + the "Feature Requests & Feedback" section of each file. Do not re-read entire reports. + Use bounded reads — load the Feature Requests table content, not the full file. ## Confinement Rules @@ -257,3 +329,10 @@ Generate the report as a Markdown file following this exact structure. Every sec - **NEVER** make live MCP calls during report generation — introspection only (consult your existing tool-call history) - **NEVER** modify `memtrace-adapter.mjs`, `package.json`, or any existing files - **NEVER** require or rely on internet access — this is an offline introspection workflow +- **ALWAYS** assign a severity score AND justification to every friction entry — no blank severity fields +- **ALWAYS** use the defined 1-5 severity scale (Cosmetic→Critical) — do not invent custom scales or labels +- **NEVER** assign severity without a justification that references concrete task impact (blocks, delays, rework required) +- **ALWAYS** keep justifications to 1-2 sentences — do not write paragraph-length justifications +- **ALWAYS** read all existing telemetry reports from `_bmad-output/telemetry/` before writing the Feature Requests section — this is mandatory even if you believe no prior reports exist +- **NEVER** create a duplicate feature request if a highly similar entry already exists in prior reports — increment the upvote count on the carried-forward entry instead +- **ALWAYS** carry forward all Active prior feature requests with their accumulated upvote counts — the latest report is the canonical Feature Request ledger; do not silently drop prior requests. Skip entries with Status=Implemented or Status=Rejected.