Plan Effort Estimate

Contributors🕹️Myles Henaghan

When to use: Active WIP plan execution under AI-assisted delivery — assign Fibonacci points per step, record progress, and let the bundled script compute totals and remaining effort. For wall-clock planning (gap analysis, remediation drafts, sprint capacity), use the wall-clock T-shirt scale instead — see effort-scales.yaml.

Instructions

1) Use the AI-assisted Fibonacci scale

Size each step using references/scale.md. Standard range 1 → 8; reserve 13 for epics (~two 8s or more).

The agent assigns one Fibonacci value per step and one per phase/plan rollup. Rollups are sized by judgement — they are not sums of child steps.

When converting from a remediation plan (Trivial / Small / Medium / Large), use the indicative mapping in effort-scales.yaml as a starting point, then re-size for AI-assisted delivery context.

2) Never mental-arithmetic totals

Do not sum points, compute percentages, or derive remaining effort in prose. Always run the deterministic script after updating the effort JSON.

node library/skills/plan-effort-estimate/scripts/validate-effort.mjs \
  --input path/to/plan.effort.json

Scan every effort file under a docs tree (for CI in consuming repos):

node library/skills/plan-effort-estimate/scripts/validate-effort.mjs \
  --scan path/to/docs

node library/skills/plan-effort-estimate/scripts/summarize-effort.mjs \
  --input path/to/plan.effort.json --pretty

For a paste-ready markdown block with Done and Left columns per step (including partial in_progress work), use the 👀 layout outputs:

# 👀 Top of plan (after title / metadata)
node library/skills/plan-effort-estimate/scripts/summarize-effort.mjs \
  --input path/to/plan.effort.json --markdown-top

# Bottom of plan (after risks / next actions)
node library/skills/plan-effort-estimate/scripts/summarize-effort.mjs \
  --input path/to/plan.effort.json --markdown-breakdown

Legacy combined block (--markdown) remains for one-shot paste but prefer the split layout. --markdown-bluf is a deprecated alias for --markdown-top.

After changing calculation logic, run the self-test:

node library/skills/plan-effort-estimate/scripts/self-test.mjs

Or from the hoen-library repo root:

npm run test:plan-effort-estimate

Copy rollup fields from the script output into the plan markdown. The 👀 headline reads:

👀 26.6% complete

21 / 79 effort points · 4 / 14 steps · 58 remaining

1. Percent — percent_complete as the ## 👀 heading (effort-based)
2. Effort — completed / total points (includes partial in_progress work)
3. Steps — by_status.done of count (fully complete steps only)

Link to the breakdown: [Effort breakdown ↓](#effort-breakdown).

Semi-completed steps: for in_progress items, Done = effort - effort_remaining and Left = effort_remaining. If effort_remaining is omitted, the step counts as 0 done and full effort left until marked done. Example: A.5 at effort 5 with effort_remaining: 1 → 4 done · 1 left.

3) Write effort data as JSON

Follow references/input-format.md. Store the file next to the plan doc, e.g. docs/wip/auth-migration.effort.json.

Agent responsibility	Script responsibility
Fibonacci effort per step/rollup	Sum total
status per item (done, in_progress, not_started, blocked)	Sum completed and remaining
Optional effort_remaining on in_progress steps	percent_complete, by_status.done / count
label, notes, narrative context	Validation (Fibonacci values, status enums)

Status values follow plan-status.yaml (JSON column).

4) 👀 plan layout — split top and bottom

Follow references/plan-layout.md. Do not repeat the Fibonacci scale table in the plan — watermark to this skill instead.

👀 Top (after title / metadata):

1. ## 👀 {percent}% complete — from --markdown-top
2. Effort · steps · remaining lines
3. Phase rollups summary line
4. Anchor link: [Effort breakdown ↓](#effort-breakdown) · *.effort.json · scale watermark
5. ### Phase status table — phase rollups (included in --markdown-top)

Then (human-authored, fixed order):

1. ## Recent progress (YYYY-MM-DD) — evidence-based changelog
2. ## Goal — outcome and scope boundary
3. Plan body — decisions, architecture, phased delivery, risks, open questions

Bottom (near end of doc):

1. ## Effort breakdown — from --markdown-breakdown
2. One-line watermark to skill + references/scale.md (no scale table)
3. Per-phase step tables — Step | Effort | Done | Left | Progress | Notes
4. Phase rollup table — effort from groups[] (not summed from steps)

Examples:

• Template: references/wip-plan-template.md
• 👀 top: assets/auth-migration.top.md
• Breakdown bottom: assets/auth-migration.summary.md

Progress column values: use markdown labels from plan-status.yaml.

5) Workflow checklist

• [ ] Read the plan and list leaf steps with stable ids (A.1, B.2, …).
• [ ] Assign Fibonacci effort per step using the scale.
• [ ] Set status from repo evidence (do not guess done).
• [ ] For in_progress steps with meaningful partial completion, set effort_remaining.
• [ ] Add or update groups rollups sized independently.
• [ ] Write/update *.effort.json beside the plan.
• [ ] Run summarize-effort.mjs --markdown-top → paste at top (includes phase status table)
• [ ] Write/update ## Recent progress and ## Goal in fixed order
• [ ] Run summarize-effort.mjs --markdown-breakdown → paste at bottom
• [ ] Apply task description rules from remediation-plan task sizing when writing labels.

6) Example

See assets/auth-migration.effort.json — sourced from hoen-assessment auth migration sizing.

node library/skills/plan-effort-estimate/scripts/summarize-effort.mjs \
  --input library/skills/plan-effort-estimate/assets/auth-migration.effort.json \
  --markdown-top

node library/skills/plan-effort-estimate/scripts/summarize-effort.mjs \
  --input library/skills/plan-effort-estimate/assets/auth-migration.effort.json \
  --markdown-breakdown

Rendered examples: assets/auth-migration.top.md (👀 top), assets/auth-migration.summary.md (bottom).

---

References

• WIP plan layout (👀 top summary)
• WIP plan template (copy skeleton)
• Effort scales taxonomy (router)
• Plan status crosswalk
• AI-assisted Fibonacci scale
• JSON input format
• Example: auth migration effort JSON
• Example: auth migration 👀 top
• Example: auth migration breakdown (bottom)
• Related: plan-work, remediation-plan

---

Troubleshooting

Symptom	Likely cause	Fix
Script rejects effort value	Non-Fibonacci number used	Use only 1, 2, 3, 5, 8, or 13
effort_remaining error	Value exceeds effort or not Fibonacci	Set remaining ≤ effort; both must be Fibonacci
Step totals disagree with phase rollup	Rollups are independent by design	Keep both; rollups reflect epic judgement, steps reflect granular work
percent_complete seems low	in_progress without effort_remaining	Add effort_remaining when partial work is done, or mark substeps done
Agent summed points in markdown	Skipped the script	Re-run summarize-effort.mjs and replace hand-calculated numbers
CI needs to gate effort JSON	No validate step wired	Run validate-effort.mjs --scan docs in consuming repos