Repository source: docs/plans/effort_estimation_trial/effort_estimation_trial_step3_development_plan.md
Debug mode: enabled
Effort estimation trial — development plan
Completion Contract
Deliver documentation-only setup for the maintainer and future agents: a resumable ledger, six useful proposed scopes with preserved estimates, and vendored Railspike instructions that capture total-cycle projections during normal selected-feature work. Allowed files: docs/railspike/RAILSPIKE.md, the eight step/phase files explicitly named in Step 2 under docs/railspike/docs/workflow/, docs/reference/railspike_workflow.md, this cycle’s step artifacts/debug log, docs/plans/effort_estimation_trial.md, the separate maintainer checklist, and this feature’s planning-index entry, including approved organization. Feedback, backlog, reference sources and AGENTS.md remain read-only; no application/runtime/deployment changes. Keep reusable mechanics in vendored instructions and project data in the host ledger; upstream roll-up is separate future work. Preserve estimate history through dated additions; restore sources and verify hashes before rating. Setup acceptance requires document/evidence checks and four workflow walkthroughs, not feature delivery or six completed study outcomes. Runtime/UI/deployment checks are inapplicable.
Key Risks
Stale feedback can misstate remaining work: check planning/status evidence before selection, preserve initial ratings before detailed code inspection, and retain replacements visibly.
Anchoring or ambiguous score semantics can spoil comparisons: freeze references and exposure records first; use total-cycle estimates and distinguish retrospective closeout from projections.
Missing workflow wiring can lose checkpoints across sessions: verify the vendored entrypoint and resumption instructions; never fabricate earlier scores.
A skewed sample can weaken ceiling conclusions: assess size diversity during selection, prioritize usefulness and qualify later conclusions rather than impose quotas.
Stage 1 — Protocol and provenance
Goal: Establish the study record before candidate rating.
Dependencies: Step 3 approval, feature branch, plan organization and planning commit.
Expected changes: Ledger protocol, source hashes, reference version, exposure records, checkpoint snapshot fields and append-only revision rules. Define candidate/outcome/split statuses and later closeout evidence.
Verification approach: Check source links/hashes and distinguish inherited, intake, step projections and retrospective assessments.
Risks or open questions: Changed/unavailable references block dependent rating until restored or explicitly versioned; retain missing checkpoints as missing.
Canonical components/API contracts touched: Ledger; calibration report, diff review and feedback summary as read-only sources; no APIs.
Stage 2 — Six scoped candidates
Goal: Propose useful unfinished outcomes and preserve initial estimates.
Dependencies: Stage 1 verified and committed.
Expected changes: Six candidate records with sources, starting revision, outcome/recovery, acceptance evidence, dependencies, prior work, inherited score and initial scoped estimate; append inspection-driven revisions separately.
Verification approach: Trace requests to feedback/current status, check overlaps, and confirm initial estimate ordering before detailed implementation inspection.
Risks or open questions: Unsuitable candidates are replaced visibly; if six cannot be supported, resolve selection before declaring setup complete. Size diversity is optional.
Canonical components/API contracts touched: Ledger; read-only backlog and feature records; no APIs.
Stage 3 — Vendored workflow integration
Goal: Make checkpoint recording part of ordinary selected-study cycles.
Dependencies: Stage 2 verified and committed.
Expected changes: Canonical experimental estimation contract in
docs/railspike/RAILSPIKE.md, with concise hooks in the eight approved step/phase files. Keep host-specific source paths and candidate data out of the reusable contract. Update the project workflow reference to document local divergence and preservation during future subtree updates without changing upstream provenance identifiers. Cover intake, Step 1 when used, Steps 2–3, Step 4 entry/revisions and retrospective closeout; record unchanged scores and link artifact snapshots. Preserve all approval gates and scope ledger updates into each feature’s closeout.Verification approach: Follow vendored entrypoint and phase hooks through to host study records; check trial-only applicability, relative links, approved checkpoint semantics and unchanged approval/commit rules.
Risks or open questions: Duplicate guidance can drift; keep one canonical contract and small hooks. Local edits invalidate the project reference’s “without local edits” claim: correct that claim and record the patch boundary. Do not apply the experiment to unrelated work.
Canonical components/API contracts touched: Vendored entrypoint and approved step/phase instructions, host workflow reference and ledger; no APIs.
Stage 4 — Walkthroughs and handoff
Goal: Verify resumption and leave a usable study handoff.
Dependencies: Stage 3 verified and committed.
Expected changes: Record walkthrough evidence in the implementation summary; update the separate personal checklist and ledger next action. Preserve the boundary between setup completion and future outcomes.
Verification approach: Walk through a new cycle, skipped Step 1, revised step and resumed cycle with missing checkpoints. Verify source/plan links, immutable earlier snapshots, unchanged-score confirmation, retrospective labeling, file scope and candidate completeness. Check that generic vendored instructions do not embed this checkout’s paths and that unrelated cycles remain unaffected. Label synthetic examples as walkthroughs, not study evidence.
Risks or open questions: Synthetic values must not enter real candidate histories; unresolved checks block setup completion.
Canonical components/API contracts touched: Summary, ledger and maintainer checklist; no APIs.
Each stage is scoped to roughly one hour; resolve material risks before dependent work. Complete verification, update the implementation summary and commit each stage before starting the next. Later feature cycles own ledger closeout updates; the six-outcome assessment is a separate documentation cycle.
Request reconciliation
The per-step projection request and direct vendored-file scope were explicitly approved in revised Step 2. This replaces the earlier host-only integration plan; its temporary caution notices have been removed now that reconciliation is complete. This plan implements that boundary; earlier checkpoint scores for this already-running setup have not been invented. The experiment applies to selected study cycles. Step 3 approval is pending.