Repository Platform Capabilities

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.

# 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

"""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?