effort-estimator

name	effort-estimator
description	Estimates how much work is left on an open Drupal AI issue (Active or Needs work) on a 1–5 scale by reading the issue, comments, any existing MR, and the current code in repos/ai. Writes effort/{nid}/effort.json and effort/{nid}/solution.txt for the web UI.

Effort Estimator Skill

You estimate how much work is left to land a fix or feature for an open Drupal AI issue. The output is a number 1–5 plus a short solution explanation. Both files live under effort/{nid}/ and are surfaced in the web UI.

Scope

Only estimate effort for issues that are:

• Active (status 1) or Needs work (status 13).

For other statuses (Needs review, RTBC, Postponed, etc.), the issue isn't waiting on someone to write code right now, so an effort estimate isn't useful. If the user asks about an issue that's in another status, tell them and skip it.

Effort scale

Score	Meaning
1	One-line bug fix. Single regex / typo / null check. Maybe a single test.
2	Small bug fix or polish across a handful of lines in 1–2 files. Possibly a small test.
3	Medium feature or non-trivial bug fix touching multiple files in one subsystem. New methods, a small new class, or a focused refactor. Tests usually required.
4	Larger feature or cross-cutting refactor. Multiple subsystems, new abstractions, schema/config changes, integration tests.
5	Major refactor with breaking API changes, update hooks, data migrations, deprecations, and significant rewrites across the module.

When in doubt, pick the lower score. The goal is to surface "easy wins" reliably; over-estimating dilutes that signal.

Inputs

For each issue, look at:

1. Local issue state at drupal-issue-hygiene-helper/state/3346420/latest_state/*_{nid}.json. Glob to find by nid. Read:
   • title, body, field_issue_category_name
   • comments (the array — content + any [Issue changes: ...] markers)
   • has_merge_request, merge_request_urls, mr_status, ci_status
2. Pre-review at reviews/{nid}.md if it exists. Pre-reviews often spell out exactly what's wrong.
3. The MR diff if one exists. Fetch {mr_url}.diff to see how much code is already written. If most of the work is already in the MR, the remaining effort is just review/test polish.
4. The codebase under repos/ai/. Look at the files the issue references — read the relevant classes/methods so you can judge whether the fix is one line or a refactor. Do NOT modify anything under repos/.

Workflow

Step 1: Confirm the issue is in scope

Read the state file. If the status is not Active (1) or Needs work (13), tell the user and stop.

Step 2: Skip if already estimated

If effort/{nid}/effort.json already exists and the user did not explicitly say "redo" or "refresh", skip and tell them which file already exists.

Step 3: Gather context

• Read the issue body and comments.
• Read the pre-review if any.
• If there's an MR, fetch the diff ({mr_url}.diff) and read it. Note the file count and rough line count.
• Open the relevant files under repos/ai/ referenced by the issue / pre-review / MR. You're trying to answer: given what's already done, how much code does someone need to write to land this?

Step 4: Decide the score

Apply the scale above. Lean lower when uncertain. Important: the score is for remaining effort, not total scope. If the issue is huge but an MR has already done 90% of the work, the remaining effort might be a 1 or a 2.

Step 5: Write the files

Create the directory effort/{nid}/ and write two files:

effort/{nid}/effort.json — a small JSON object:

{
  "effort": 3,
  "rationale": "One-line summary of why this score (max ~140 chars).",
  "has_mr": true,
  "estimated_at": "2026-04-08T14:30:00Z"
}

The effort field MUST be an integer 1–5. The web UI parses this directly.

effort/{nid}/solution.txt — a plain-text explanation of what should be done. Aim for 5–25 lines. Cover:

• What the actual fix is (which file/class/method, what to change)
• Why this is the right approach
• Any test or doc work that should ship with it
• If an MR exists: what's already done vs what's left

Plain text only. The web UI shows this in a modal when the user clicks the effort badge.

Step 6: Report

Print a one-line summary: {nid} ({status}): effort=N — {one-line rationale}. If you processed several issues, list them in order of effort ascending so the easy wins float to the top.

Important notes

• This skill writes only to effort/{nid}/. Never modify state files, the helper, the repo, or reviews.
• If the user asks to estimate "all" active/needs-work issues without specifying, ask them to confirm the scope first — there may be 200+ issues and that's a lot of code reading.
• If you can't open a file in repos/ai/ because it doesn't exist, that itself is a signal: the issue may be outdated, and the effort score should reflect that (often a 1 — close as fixed/outdated).
• Effort is about remaining work, not the historical scope of the issue. An MR that's 95% done deserves a low score.
• Rate limits: Don't fetch the same MR diff twice in one run — read it once and reuse.