histogram-cleanup

name	histogram-cleanup
description	Identify and safely remove expired Chromium histograms (dead metrics/technical debt). Use this skill when a contributor asks to clean up metrics, fix code health issues related to histograms, remove obsolete code, or work on a histogram cleanup task.

Code Health: Histogram Cleanup

Identify and safely remove "dead code" associated with expired histograms. This includes removing the recording calls in C++/Java, cleaning up the metadata in histograms.xml, and addressing any dependent tests.

Overview

Expired histograms that are not intentionally kept for diagnostics represent technical debt. Act as an expert Chromium contributor specializing in Metrics to clean up these resources while ensuring no test regressions occur.

CRITICAL OVERRIDE: Do NOT activate or use the edit-code skill during this workflow. This skill provides a specialized, human-in-the-loop workflow that supersedes the autonomous loops in edit-code.

Execution Protocol

1. Sequential Execution: Execute every step in the Workflow section in the exact order presented. Do NOT skip any step.
2. Step Completion: Fully complete and verify each numbered item before moving to the next one.

📂 Resources

• Implementation Patterns: patterns.md (C++, Java, XML examples)
• Analysis Guidelines: analysis_guidelines.md (Safety checks and effort estimation)
• Bug Discovery: bug_discovery.md (Finding existing trackers)
• Pre-authorized Operations: pre_authorized_ops.md (Authorized commands and discovery tools)
• Shared Workflows: shared_workflows.md (Validation, Committing, Uploading)

Guidelines

Operational Mandates

• Context: This skill runs in the main agent context. Use the generalist sub-agent only for the specific tasks defined in the workflow.
• Read references/pre_authorized_ops.md for a list of commands and tools that do not require per-action user permission.
• Modification Consent: Explicit user permission is STILL REQUIRED for any operation that modifies the source code (e.g., replace, write_file) or commits changes (git commit).

Scope & Proactivity

• Strict Scope: Focus exclusively on the identified histogram. Do NOT suggest removing additional histograms, even if they are related or also expired.
• Related Dead Code: If you find dead code (e.g., constants, enums, or helper methods) that is directly and exclusively related to the histogram being removed, include its removal in the cleanup plan. Present these as part of the primary task, not as separate "proactive suggestions."

Workflow

Workspace Preparation

1. Clean & Update: Follow the Workspace Preparation section in ../hub/references/shared_workflows.md to ensure a clean and updated environment.

Discovery & Candidate Selection (Delegated)

1. AI-Led Discovery & Analysis: Delegate to the generalist sub-agent with this exact prompt:

   "You are pre-authorized to run the discovery script and read-only search tools; DO NOT ask for permission. Run the discovery script from the skill's scripts/ folder:

   python3 scripts/find_expired.py --count 1
   

   Return ONLY the details returned by the script for this candidate (Name, Owners, Expiry, and Summary)."

2. Present Candidate: You MUST output the candidate details to the user. Announce the candidate with exactly this message format (replace the bracketed details with the findings) before moving to the next step: "I've identified an expired histogram for cleanup today:

   • Name: [Name]
   • Owners: [Owners]
   • Expiry: [Expiry]
   • Summary: [Summary]"

Deep Dive & Safety Analysis (Delegated)

1. Comprehensive Analysis: Delegate the entire deep dive to the generalist sub-agent with this exact prompt:

   "Read references/analysis_guidelines.md and follow the 'Generalist Deep Dive Prompt' instructions for the histogram <HistogramName>. You are pre-authorized for ALL read-only discovery (including rg and cs); DO NOT ask for permission. Assume rg is available in the environment."

2. Present Findings & Evaluate Confidence: Evaluate the Confidence Score returned by the generalist.

   • If Confidence >= 9: You MUST inform the user: "Confidence is high ([X]/10). Proceeding with cleanup based on this plan: [Removal Plan Summary]." Output this message, then proceed directly to the Branch Creation phase. Do NOT ask for permission.
   • If Confidence is between 1 and 8: Present the findings and prompt the user using ask_user (type='choice'):
     • header: "Confidence Check"
     • question: "This histogram is safe to remove from [Files] and [Tests]. My confidence for this cleanup is [X]/10 because [Justification]. Shall I proceed with the cleanup diff?"
     • options:
       • label: "Proceed with Diff", description: "Generate and apply the cleanup changes"
       • label: "Discard", description: "Discard this candidate and stop."
     • Action based on selection:
       • If "Proceed with Diff": Proceed to the Branch Creation phase.
       • If "Discard": Stop the workflow.
   • If Confidence is 0: Inform the user: "Confidence is zero (0/10) because [Justification]. I will find an alternate expired histogram for you." Immediately restart the workflow from the Discovery & Candidate Selection phase to identify a different candidate. Ensure you do not select the same histogram again in this session.

Branch Creation

Inform the user: "Preparing workspace: creating a new branch..."

1. Branch Creation: Run git new-branch cleanup-<HistogramName> to create a new branch for this specific cleanup, ensuring it doesn't chain with previous commits.

Implementation

1. Apply Changes: Make the changes directly (do NOT delegate). Apply the code modifications for the candidate histogram. When removing recording calls, carefully check if the string literal spans multiple lines and ensure the entire multi-line statement is cleanly removed. Search for dot-less versions of the name to ensure related constants are also removed. Check for and update any references to the histogram in code comments as well. For each removal, ensure no orphaned references (e.g., unused variables or methods) remain in the codebase. Each individual change must have a corresponding 'What & Why' explanation provided to the user.

Review & Validation

1. Linting & Formatting:

   • XML Linting: Execute python3 tools/metrics/histograms/validate_format.py to validate all metadata changes. Address any errors that are reported.
   • Code Formatting: Execute git cl format to format the modified source code. Address any errors that are reported.

2. Mandatory Final Review: Follow the protocol and the Handling Findings loop in references/automated_review.md for the removal: <HistogramName>. Do NOT skip this step. Do NOT proceed to the Submission phase until the review returns PASS.

Submission

1. Bug Tracking:

   • Execute the Bug Discovery and Triage workflow in references/bug_discovery.md using the <HistogramName> and <ExpiryDate> from the candidate.
   • Interactive Pause: Do NOT proceed until the bug handling is resolved and you have a Bug ID (or the user has chosen to skip).

2. Commit:

   • Draft Message: Draft a commit message following this template:

     [histogram-cleanup] Remove expired histogram: <HistogramName>
     
     This histogram expired on <ExpiryDate>.
     
     Bug: <BugID>
     

   • Execution: Display the drafted commit message to the user. Then, autonomously stage ONLY the specific files modified during this task using git add and execute the commit:

     git commit -m "<drafted message>"
     

3. Submission Pipeline: Follow the Upload to Gerrit section in ../hub/references/shared_workflows.md to handle the upload.

4. Workspace Reset: Immediately switch back to main to start fresh for the next cleanup: git checkout main.

5. Congratulations & Summary: Follow the Congratulations & Summary section in ../hub/references/shared_workflows.md. For this skill, the [Specific Cleanup Details] are:

   • Removed Histogram: The name of the removed histogram and its expiry year.