--- title: 'Repository Platform Capabilities' source: 'https://academia.sh/en/courses/code-review/repository-platform-capabilities' course: 'Code Review and Team Process' language: en updated: '2026-08-17T18:10:47+00:00' license: 'CC BY-SA 4.0' --- # Repository Platform Capabilities The five-capability chain drops from 45 units to 21, but found stays at 15, missed at 9, and unwritten missed at 2 in every row; the individual gains range from 2 to 7 and only discussion's gain grows with round count — 4, 6, 12. The previous two lessons built the flow's rules with text: the contribution guide was a text, ownership was a mapping text. There is also a surface these rules run on — the capabilities where the work item is recorded, the queue is seen, discussion attaches to the change, merged work gets published, and the published becomes consumable. These capabilities are taken up not as products but as **classes**: issue tracking, board, discussion, release publishing, package registry. Which hosting surface they stand on is not this lesson's subject, and the same classes will still exist five years from now. This lesson has a single question: **which transition of the chain does each capability shorten, and by how much?** ## Five Capability Classes **Issue tracking** is where a proposal gets recorded. When a proposal does not turn into a record, it stands somewhere as a spoken thing, and its entering the queue depends on someone remembering it. Recording binds the proposal to the chain's first transition. **Board** is the surface where work items are laid out by status. As measured in the previous lesson, it shows accumulation, not rate; its contribution is speeding up the **taking on** of the next item in the queue. If no one sees what is in the queue, taking something from the queue depends on someone asking. **Discussion** is where a finding and the counter-view **attach** to the change. If a finding stands in a conversation outside the change, the next round has to reconstruct it: which line, which reasoning, which counter-proposal. Attached discussion removes this reconstruction. **Release publishing** is the capability that binds merged work to a point and announces it outward. **Package registry** is where published work becomes **pullable** as a dependency. The two touch separate transitions, and both are after review. What the five share is that each keeps a **record**. The record's fields determine what the capability can do in the chain. ```text # example work item record — not executed id : #377 status : in review class : interface requirement : outbound-call timeout must be configurable linked proposal : #361 change : payment-timeout discussion : 4 notes, 2 attached to a line release : — ``` The `status` field gives the item's column on the board, the `change` field says which change meets this item, the `discussion` field says where the findings attach, and the `release` field says whether the work has been published. If a field is empty, that link of the chain cannot be measured: in a repository where the `release` field is never filled, the `merged→closed` transition's duration is not known. ## Capabilities Linked to Each Other What makes the measurement possible is capabilities being **linked to each other**, not standing alone. The chain's wait is measured at transitions, and measuring a transition requires both ends to be bound to the same identity: which work item a proposal belongs to, which change a work item belongs to, which discussion a change belongs to, which release the merged work belongs to. When the link breaks, the loss is not only traceability. A finding standing in a conversation detached from the change requires that finding to be reconstructed in the next round, and in the measurement this is exactly discussion's gain — the round duration dropping from **6** to **4** is the repair cost of a broken link. The same logic works at the chain's end too. Which work items a release note covers comes from the link between the release and the items. Without the link, the note is written by hand, and a hand-written note is a list no one can verify. This lesson measures the link's effect on **wait**; the note's effect on **the reader** is the next lesson's subject. ## Every Capability Touches One Transition The measurement's design rests on a single rule: **a capability touches only one transition.** If a capability is said to help in more than one place, the measurement loses its meaning; where a gain comes from can no longer be separated. The mapping is this: issue tracking touches `proposal→queued`, board touches `queued→in progress`, release publishing touches `merged→closed`, package registry touches `closed→available`. Discussion touches none of these; it touches **round duration**. The last transition is added in this lesson. The previous lesson's chain ended at the work item's closing; package registry touches one step beyond that, the work becoming **consumable** by someone else. This step is not the work item's status and does not show up on the board, but it is where the chain's reader is waiting. ## Round Count vs. Round Duration Discussion standing apart makes a distinction necessary. **The number of review rounds** and **the duration of one round** are not the same thing. What determines round count is what is found in the first round, and this has been the result of axis assignment since the start of the course. What determines a round's duration is how intact a finding carries from one round to the next. The practical consequence of this distinction is: **no platform capability lowers round count.** Round count is determined by what review sees, and a surface does not change seeing. The capabilities touch wait, and discussion also touches wait — only its multiplier is different, because it changes the wait written per round and gets multiplied by round count. The measurement's assumptions: - **TF22** — The shared setup's 600-line change and 24 defects are used as they are; the class distribution and the oracle are the course's constant. - **TF23** — The chain is the previous lesson's transitions, with **8** units added at the end for `closed→available`. The other four transitions are **5**, **9**, **2**, and **3** units. - **TF24** — Every capability lowers **a single transition's** wait to a new value: issue tracking **1**, board **4**, release publishing **1**, package registry **1**. The values represent the state where the capability exists and is used. - **TF25** — Discussion touches not a single transition but **wait per round**, lowering it from **6** to **4**. The reasoning is that attached discussion removes the reconstruction that would otherwise happen between rounds. - **TF26** — The main measurement's assignment is `three reviewers, separate axes`. The second measurement tests discussion separately across four assignments; nothing else changes. - **TF27** — The capabilities do not touch defects found. A surface neither adds an axis nor grows attention; this assumption is tested along with the measurement's result and confirmed in the table. - **TF28** — The set's resolution at 24 defects is **1/24**; the smallest measurable difference in the chain is **1 unit** of wait. ## Measurement ```python """Repository platform capabilities: the single transition each capability touches. Part 1 - five capabilities one by one and together; does found or missed change. Part 2 - the gain of the round-duration capability across four assignments. """ SEED = 20260815 AXES = ("interface", "implementation", "test", "documentation", "style") UNWRITTEN = "unwritten requirement" CLASSES = AXES + (UNWRITTEN,) ATTENTION, CHUNK = 12, 50 # Chain: the work item's transitions, plus the final step reaching the consumer. CHAIN = {"proposal→queued": 5, "queued→in progress": 9, "in progress→in review": 2, "merged→closed": 3, "closed→available": 8} ROUND_WAIT = 6 # Each capability touches a single transition; discussion touches round duration. CAPABILITIES = { "issue tracking": ("proposal→queued", 1), "board": ("queued→in progress", 4), "discussion": ("round duration", 4), "release publishing": ("merged→closed", 1), "package registry": ("closed→available", 1), } def rng(seed): d = seed % 2147483646 + 1 def draw(n): nonlocal d d = (d * 48271) % 2147483647 return d % n return draw def change(lines, defect_count=24, seed=SEED): draw, defects = rng(seed), [] chunk_count = max(1, lines // CHUNK) for i in range(defect_count): defects.append({"no": i + 1, "class": CLASSES[draw(6)], "chunk": draw(chunk_count)}) return {"lines": lines, "chunks": chunk_count, "defects": defects} def review(d, axes, attention=ATTENTION): read = set(range(min(attention, d["chunks"]))) return {k["no"] for k in d["defects"] if k["class"] in axes and k["chunk"] in read} def panel(d, assignments, attention=ATTENTION): found = set() for axes in assignments: found |= review(d, axes, attention) return found def review_rounds(found, defect_count, wait_per_round=ROUND_WAIT): remaining, rounds, wait = defect_count - len(found), 1, wait_per_round while remaining > 0 and rounds < 6: rounds += 1 wait += wait_per_round remaining -= max(1, len(found) // 2) return rounds, wait, max(0, remaining) def chain_total(d, assignment, enabled): """Chain's total wait with the enabled capabilities' settings.""" transitions = dict(CHAIN) round_duration = ROUND_WAIT for name in enabled: step, value = CAPABILITIES[name] if step == "round duration": round_duration = value else: transitions[step] = value b = panel(d, assignment) rounds, wait, remaining = review_rounds(b, len(d["defects"]), round_duration) return sum(transitions.values()) + wait, rounds, wait, b, remaining FULL = set(AXES) ASSIGNMENTS = { "single reviewer, all axes": [FULL], "three reviewers, same axis": [{"implementation"}] * 3, "three reviewers, separate axes": [{"interface"}, {"implementation"}, {"test", "documentation"}], "five reviewers, five axes": [{a} for a in AXES], } d = change(600) MAIN = ASSIGNMENTS["three reviewers, separate axes"] baseline, t0, b0, found0, _ = chain_total(d, MAIN, []) print(f"assignment: three reviewers, separate axes | chain {baseline} | rounds {t0} | " f"review {b0} | found {len(found0)} | missed {24 - len(found0)}") print() print(f"{'capability':<20s} {'transition touched':<23s} {'rounds':>3s} " f"{'chain':>6s} {'shortened':>7s} {'found':>7s} {'missed':>5s} " f"{'unwritten':>10s}") for name in CAPABILITIES: z, rounds, _, b, _ = chain_total(d, MAIN, [name]) unwritten = sum(1 for k in d["defects"] if k["no"] not in b and k["class"] == UNWRITTEN) print(f"{name:<20s} {CAPABILITIES[name][0]:<23s} {rounds:3d} {z:6d} " f"{baseline - z:7d} {len(b):7d} {24 - len(b):5d} {unwritten:10d}") z, rounds, _, b, _ = chain_total(d, MAIN, list(CAPABILITIES)) unwritten = sum(1 for k in d["defects"] if k["no"] not in b and k["class"] == UNWRITTEN) print(f"{'all five together':<20s} {'—':<23s} {rounds:3d} {z:6d} {baseline - z:7d} " f"{len(b):7d} {24 - len(b):5d} {unwritten:10d}") print() print(f"{'assignment':<32s} {'rounds':>3s} {'no discussion':>13s} " f"{'with discussion':>16s} {'shortened':>7s}") for name, assignment in ASSIGNMENTS.items(): without, rounds, _, _, _ = chain_total(d, assignment, []) with_disc, _, _, _, _ = chain_total(d, assignment, ["discussion"]) print(f"{name:<32s} {rounds:3d} {without:13d} {with_disc:16d} {without - with_disc:7d}") ``` ``` assignment: three reviewers, separate axes | chain 45 | rounds 3 | review 18 | found 15 | missed 9 capability transition touched rounds chain shortened found missed unwritten issue tracking proposal→queued 3 41 4 15 9 2 board queued→in progress 3 40 5 15 9 2 discussion round duration 3 39 6 15 9 2 release publishing merged→closed 3 43 2 15 9 2 package registry closed→available 3 38 7 15 9 2 all five together — 3 21 24 15 9 2 assignment rounds no discussion with discussion shortened single reviewer, all axes 2 39 35 4 three reviewers, same axis 6 63 51 12 three reviewers, separate axes 3 45 39 6 five reviewers, five axes 2 39 35 4 ``` ## Reading What Is Shortened The chain's baseline is **45** units. Opened one by one, the capabilities' gain ranges between **2** and **7**, and the ordering is: package registry **7**, discussion **6**, board **5**, issue tracking **4**, release publishing **2**. What determines the ordering is not the capability's importance, it is the **starting length** of the transition it touches. Package registry shortens the most because `closed→available` was the longest transition — **8** units. Release publishing shortens the least because the transition it touches was already **3** units and there is no room to shorten there. This says a capability's value **depends on its place in the chain**: the same capability sits in a different order in a different chain. Opened all five together, the chain drops from **45** to **21**; the gain is **24** units, that is, **53%** of the chain. The sum of the individual gains is also **24**, and this is not a coincidence — because each capability touches a separate transition, the gains do not mix and can be added. If two capabilities touched the same transition, the total would be smaller than the sum of the individual gains. The `rounds` column is **3** in all six of six rows. No capability lowers the round. While the chain's total is cut in half, round count does not budge at all: **shortening wait and shortening rounds are separate jobs**, and these surfaces do only the first. ## Discussion's Exception The second table tests discussion separately across four assignments and shows something that does not show up in a single table: discussion's gain is **not fixed.** In the two-round assignments it is **4** units, in the three-round one **6**, in the six-round one **12**. The reason is in its definition. Discussion lowers wait per round from **6** to **4**; the gain is **2** units per round and gets multiplied by round count. The other four capabilities touch the chain's **fixed** part and their gains are independent of the assignment — whatever the assignment is, package registry shortens by **7** units. An ordering rule follows from this. **In a chain where review is good, discussion's gain is one of the smallest capabilities; in a chain where review is bad, it is the largest.** In the six-round row, discussion shortens by **12** units, more than package registry's **7**. So a capability's ordering changes depending on the state of the team's review, and a fixed priority list cannot be written. The same row carries a warning too. The six-round assignment's chain with discussion is **51** units; it is still longer than the two-round assignment's without-discussion **39**. **No capability closes a bad axis assignment.** A surface does not make review see what it does not see. ## The Untouched Columns The table's right three columns are the same in all six rows: found **15**, missed **9**, unwritten missed **2**. **TF27** assumed this and the measurement confirms it. This fixedness is the lesson's real finding. Five capabilities cut the chain in half and **do not get even one more defect found.** The source of finding defects has been the same since the start of the course: how many axes were looked at and how many chunks were read. A surface neither adds an axis nor grows attention; it speeds up the item's moving from one place to another. The unwritten missed column says this in the sharpest way. The **unwritten requirement** class still misses **2** even when the issue tracking capability is on — and that is exactly the capability that records the proposal. Recording puts the proposal into the chain; it does not record the requirement that was never recorded. The **requirement statement** measured in an earlier lesson was the mechanism able to touch that class, and it was not a surface, it was a **guide item**. This distinction gives a selection rule: a capability is valuable if it shortens a transition in the chain, and the amount it shortens is measurable. If a capability claims to raise defects found, that claim can only be true by changing axis count or chunks read; no capability in this table does that. ## Summary - Five capabilities are taken up at the class level — issue tracking, board, discussion, release publishing, package registry — and each touches **a single transition** in the chain. - The chain drops from **45** units to **21** when all five are opened together; the gain is **24** units and equals the sum of the individual gains, because the transitions do not overlap. - Individual gains range between **2** and **7**, and the transition's starting length determines the ordering: package registry **7**, release publishing **2**. - Round stays at **3** in all six of six rows; no capability lowers round count. Only discussion touches the round's **duration**, and its gain grows with round count: **4**, **6**, **12**. - Found **15**, missed **9**, and unwritten missed **2** are unchanged in every row: capabilities shorten wait, they do not get defects found. - The six-round assignment's chain with discussion is **51** units, still longer than the two-round assignment's without-discussion **39**; no capability closes a bad axis assignment. ## Next Step One transition was left at the chain's end and appeared in the measurement as only one number: merged work gets bound to a point and announced outward. That announcement is itself a text and it has a reader — someone who never appeared through this whole course. The next lesson measures that text: what does the **release note** tell the reader? How many questions does the gap between a list of changes and a list of the **meaning** of changes answer, and how many of the reader's questions find no answer in any note form?