Second Brain

architect-design-doc-estimates-quantify-cherry-pickport-effo

2 min read

Architect design-doc estimates — quantify cherry-pick/port effort via commit+file+line count BEFORE stating estimate

Architect-agent design documents sometimes underestimate cherry-pick/port effort by 3-5x when they state “cherry-pick N commits” without quantifying real file churn. Evidence: Hermes v0.9.0 Option C design (19-Apr-2026) estimated F2 Fast Mode as “cherry-pick 1-3 commits (small isolated patch)“. Actual upstream Fast Mode story: 6 commits (d416a692, 8394b5dd, 8779a268, 0bea6035, cdd44817, 970192f1), 473 insertions across 9 files. First cherry-pick alone hit 2 content conflicts + 1 file-location conflict on customized hermes_cli/commands.py + config.py. Safe resolution = dedicated 1-2h merge session, not inline cherry-pick. Rule for architect agents: before stating an effort estimate for “cherry-pick N commits” in a design doc, MUST run (a) git log upstream/ —oneline —grep='' to enumerate ALL candidate commits (often 3-10x more than headline commit), (b) git show —stat on each candidate to sum lines-changed and file-count. Then estimate effort as: (total_lines / 200-lines-per-hour conflict-resolution-rate) + (file_count / 5-files-per-hour conflict-triage). A 473-line / 9-file cherry-pick is at minimum 2-3 hours of careful work, not “inline cherry-pick attempt.” Architect output format update: design docs should include explicit “effort reality-check” table showing commit-count, line-count, file-count per candidate feature BEFORE the port plan. Cross-agent applicability: any agent writing design docs (architect, planner, CTO-layer estimators) when the design involves cherry-picking, merging, or porting across forked repos.

Graph View