> ## Content Index
> Fetch the complete content index at: https://contextfirst.blog/llms.txt
> Use this file to discover other available public pages before exploring further.

# README as Contract - Every Column Defined + Half-Open Windows
- URL: https://contextfirst.blog/readme-as-contract-half-open-windows/
- Published: 2026-09-06T13:00:00.000Z
- Updated: 2026-09-06T13:00:00.000Z
- Description: Two VPs, one CSV, zero shared definition of May
- Author: Iheatu Chris Wogu
- Tags: Field Notes, Engineering Management, Agentic Delivery, Learning Journey 2026

After [fixing the metrics](https://contextfirst.blog/afternoon-three-wrong-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](https://contextfirst.blog/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 |

```python
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](https://contextfirst.blog/auditing-agent-wrote-analytics/)). `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

- [The afternoon we shipped three wrong metrics](https://contextfirst.blog/afternoon-three-wrong-metrics/) \- why the glossary exists
- [Your Slack script just shipped](https://contextfirst.blog/script-to-cli-spreadsheet-product/) \- CLI as product threshold
- [Auditing analytics your agent wrote](https://contextfirst.blog/auditing-agent-wrote-analytics/) \- README drift caught in audit
- [Field notes: agentic delivery](https://contextfirst.blog/field-notes-agentic-delivery/)
- github-analysis: `0c9b610` · `e56f97e` · `ec31856`

---

![Iheatu Chris Wogu](https://avatars.githubusercontent.com/u/3457705?s=176&v=4)

## 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](https://contextfirst.blog/). Values treatise: [engineering manager values](https://contextfirst.blog/engineering-manager-values/).

**LinkedIn:** [linkedin.com/in/iheatu-chris-wogu](https://www.linkedin.com/in/iheatu-chris-wogu/?ref=contextfirst.blog)