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
This commit is contained in:
Magal 2026-05-21 06:29:22 -03:00
parent 30742f1643
commit 5d5ecb60d5
1 changed files with 94 additions and 15 deletions

View File

@ -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.