Field Notes

README as Contract - Every Column Defined + Half-Open Windows

Two VPs, one CSV, zero shared definition of May

Iheatu Chris Wogu

Iheatu Chris Wogu

— 3 min read
Share

After fixing the metrics, we fixed the documentation. Two directors can open the same May export and still argue if one hears "May" as calendar days in UTC and the other hears America/New_York half-open windows. Commits 0c9b610 / 06332ac documented every output column; e56f97e and ec31856 formalized [start, end) semantics plus --month / --timezone.

Here's what this piece covers: tribal column lore, the half-open window rule, README as the staff-meeting contract, and three lead habits.

Part of Field Notes: agentic delivery.

1. The leadership problem

Two managers run "the same May report" with different date flags - then argue in a room that should be deciding staffing. Column names like prs_reviewed invite wrong interpretations without a glossary.

Wrong: "Document your metrics someday."
Right: "Same week as the fixes: column glossary, half-open window rule, README as the staff-meeting source of truth."

The anti-pattern is tribal column lore - only the author knows what prs_merged means.

2. What the git history shows

When Commit Contract change
Jun 1 10:56 0c9b610 Short descriptions for every output column
Jun 1 11:00 06332ac Expanded column definitions
Jun 1 13:57 8e977c0 prs_closed_unmerged on person summary
Jun 1 14:02 e56f97e Half-open date window semantics in README
Jun 2 10:30 ec31856 --month and --timezone CLI options

Verified: these commits land after the morning metric corrections - documentation is part of the deliverable, not a backlog nicety.

flowchart TD F[Metric fixes morning] --> G[Column glossary] G --> H["Half-open [start, end)"] H --> M["--month / --timezone"] M --> R[README as staff-meeting SoT]

3. Half-open windows [start, end)

--month 2026-05 means start inclusive, end exclusive: [2026-05-01, 2026-06-01) in the report timezone (default America/New_York). Timezone applies to calendar boundaries - not a UTC surprise that shifts May 31 into June.

Flag / concept Meaning Example
--month 2026-05 Whole calendar month in report TZ [2026-05-01, 2026-06-01)
--since / --until Explicit half-open pair ISO timestamps, end exclusive
--timezone Calendar boundary TZ America/New_York
--merged-only Filters detail sheet population Does not redefine every person-summary count 
from zoneinfo import ZoneInfo

def may_2026(tz_name: str = "America/New_York") -> tuple[str, str]:
    """Staff-meeting May: inclusive start, exclusive end."""
    tz = ZoneInfo(tz_name)
    start = "2026-05-01T00:00:00"  # interpreted in tz → UTC for filters
    end = "2026-06-01T00:00:00"    # exclusive
    return start, end

Person summary vs PR detail sheets: different grain. prs_closed_unmerged is mutually exclusive with prs_open at window end for the same PR. After schema landed, older Excel exports can still show zeros until you re-export from cache.

4. Named pattern: README as contract

README as contract - every column defined; half-open windows [start, end) as the staff-meeting source of truth.
Column Definition (contract) Common misuse
prs_authored Opened in [start, end) Equating to "active"
prs_merged Merged in window (includes carry-over) Assuming created-in-window only
prs_open Still open at window end Treating as opened-in-window queue
prs_closed_unmerged Opened in window, closed without merge before end Double-counting with open
prs_reviewed Distinct PRs with a review submitted in window Counting comment-only activity

What broke: the README reconciliation formula once used column totals as if carry-over did not exist - the example table contradicted the formula. Caught in metrics review (article 11). d2537b3 trimmed the user-facing API limits section - operators need the run log, not a REST lecture.

5. What I'd do as a lead

  1. Treat README column defs as part of the deliverable. Review them in the same PR as the metric code.
  2. Standardize on [start, end) for all engineering reports. One window rule across tools.
  3. Publish one example TSV with annotated columns for new directors. Onboarding beats Slack archaeology.

Further reading

Iheatu Chris Wogu

About the author

Iheatu Chris Wogu is an engineering manager focused on launch programs, honest engineering metrics, and engineering-led, agent-accelerated delivery - researching where work queues up when agents widen dev output, then building proof, gates, and measurement that scale.

Field notes live on First Context. Values treatise: engineering manager values.

LinkedIn: linkedin.com/in/iheatu-chris-wogu

Read more