code_ownership_mapping v1.0.0

name: "code_ownership_mapping" description: "Map who really owns each area of a codebase and where nobody does: analyse git history with Degree of Authorship, score bus factor risk per area, flag sensitive areas with no active owner, and turn the map into CODEOWNERS entries and review routing that stay current. Use when asked who owns a part of a repo, to build or fix a CODEOWNERS file, to find orphaned or single-owner code, or to audit bus factor risk."

Code Ownership Mapping

Purpose

Answer "who owns this code" from evidence instead of memory. The skill reads git history and review records, separates real owners from people who only touched an area once, marks sensitive areas that have no active owner, scores bus factor risk per area, and produces CODEOWNERS entries that match the evidence. It also sets an upkeep rhythm so the map does not rot after the first pass.

Bundled tools:

• scripts/ownership.py analyses a local git repository and prints a per-area ownership map, with optional CSV output and a draft CODEOWNERS file.
• references/ownership-risk-worksheet.md is the scoring sheet for the human review that follows the script run.
• references/worked-example.md walks a small repo from a first map with one orphaned area to that area being genuinely re-owned.

Workflow

1. Fix identities before measuring anything

• Check the repository .mailmap first. One person committing under two emails counts as two people until the mailmap merges them, and every number after that point is wrong in a way that flatters bus factor.
• Build the handles file the script needs: one email,handle line per person, mapping commit emails to platform usernames. Without it the script still maps ownership by name and email, but it leaves TODO lines instead of guessing handles for CODEOWNERS.

2. Run the history analysis

Run:

bash
python3 scripts/ownership.py /path/to/repo --depth 2 \
  --sensitive "src/auth" --sensitive "*billing*" \
  --handles handles.csv --csv ownership.csv --codeowners CODEOWNERS.draft

• Depth sets what an area is. Depth 2 gives areas like src/auth. Pick the depth the team assigns work at, and use the same depth on every rerun so maps are comparable.
• Repeat --sensitive for each sensitive pattern. Sensitivity comes from the team, using the list in the worksheet. History alone cannot tell you an area is sensitive.
• The script counts, per file, first authorship and commits per author, then computes Degree of Authorship: DOA(d, f) = 3.293 + 1.098 times FA + 0.164 times DL minus 0.321 times ln(1 + AC), where FA is 1 if the person created the file, DL is their commits on the file, and AC is everyone else's commits on the file. The weights come from Fritz et al. (2014), and the method is the one Avelino et al. (2016) used for truck factor work.
• A person is a file author when their DOA, divided by the best DOA for that file, is at least 0.75. Treat people below that line as contributors: useful leads for backup owners, not owners yet.
• Active means the person committed in that area within the active window, measured back from the newest commit in the repo, 365 days by default. A file author outside the window is a historian, not a routed reviewer.

3. Score bus factor and risk per area

• The script adapts the Avelino greedy method per area: remove the author who covers the most files, recount how many files still have a remaining author, and stop when coverage drops below half the files. The count removed is the area bus factor.
• Read the number plainly. Bus factor 1 means one person's absence stalls that area. Bus factor 2 is fragile. Three or more is workable for most small and medium teams.
• Cross the bus factor with sensitivity and activity using the worksheet, in this order: no active file author is CRITICAL orphaned, then bus factor 1 in a sensitive area is HIGH, then the rest follow the worksheet table. Do not average scores into a single repo grade. The worst area is the finding.
• For context only: Avelino et al. reported that, in a study of 133 popular GitHub projects, 65 percent had a truck factor of two or less and 34 percent sat at exactly one. Low numbers are common. That is a reason to fix them, not a reason to accept them.

4. Check review records before trusting the map

• Git history shows who wrote code. It does not show who reviews it, who can fix production, or who holds access. For each HIGH or CRITICAL area, check recent pull or merge requests on the hosting platform: who actually reviewed the last few changes there, and did the suggested owner approve any of them?
• Ask the worksheet questions per area: can this person fix a production problem here alone, do they still have write permission, are they still on the team, and is anyone a single point of failure for access such as deploys or key rotation?
• Where review records and history disagree, believe the disagreement and investigate it. A named owner who never reviews is a routing problem, and a reviewer who never authors is a hidden owner the map should name.

5. Turn the map into CODEOWNERS

• Prefer teams over individuals where the platform supports it, so one absence does not stall reviews. Where an individual is the honest owner, name the individual and record the backup in the worksheet.
• GitHub: the file lives in the root, docs/, or .github/ directory of the branch. Each line is a gitignore style pattern followed by owners such as @username or @org/team-name. The last matching pattern wins, so write general patterns first and specific ones after. Owners must have write permission, and a team must have write permission even if its members have it individually. One line with invalid syntax can stop the file being used at all, so keep comments on their own lines and check every handle exists. Owners are requested automatically on pull requests that touch their paths, except draft pull requests. Routing only becomes a merge gate when required review from code owners is turned on in branch protection.
• GitLab: the file supports sections such as [Documentation] @docs-team with paths listed under the heading. Prefix a section with a caret, ^[Go], to make approval optional for merge requests. Add a count such as [Documentation][2] to require that many approvals. Entries outside any section are not overridden by sections, and duplicate section names combine.
• Never route a sensitive area to a stale author to make the file look complete. For an orphaned area, leave the TODO or UNOWNED line from the draft visible, name a new owner in the worksheet, and finish step 6 first.

6. Resolve orphaned and single-owner areas with real work

• A new owner earns the title by doing the work: shipping a real change in the area and reviewing the next changes there. Then rerun the script. If the rerun does not promote them, the area is not re-owned yet, whatever the CODEOWNERS file says.
• For a bus factor 1 area, name the backup in the worksheet, pair the backup on the next change, and recheck after the backup has shipped in the area.
• Accepting a risk in writing is allowed for non-sensitive areas. Record who accepted it and the recheck date in the worksheet. Silent acceptance is how orphaned areas form.

7. Keep the map current

• Rerun the script on a fixed cadence, quarterly is a sane default for an active repo, and after any of these events: someone leaves or joins, a team restructure, a new sensitive area, or a directory move or rename.
• Diff the new map against the last one. The changes are the report: areas that gained or lost an active owner, bus factors that moved, new orphans.
• Update CODEOWNERS in the same change as the map review, and run the platform check for the file: on GitHub, confirm the file is detected and a test pull request requests the expected owners before calling it done.

Output Contract

Deliver, in this order:

1. The ownership map table: area, file count, bus factor, suggested active owners, risk label, with sensitive areas marked.
2. The orphan and risk list: every CRITICAL and HIGH area, its named new owner or backup, and its recheck date.
3. The draft or updated CODEOWNERS content, with any UNOWNED or TODO lines left visible rather than filled with a stale name.
4. A short notes section: identity problems found in the history, disagreements between history and review records, and risks accepted in writing.
5. The upkeep entry: date of this run, date of the next scheduled rerun, and the events that should trigger an early rerun.

Operating Rules

• History is evidence, not a verdict. Authorship, review records, and access each show a different third of ownership. Report which sources were actually checked.
• Never present commit counts alone as ownership. A commit is a unit of activity, not of knowledge. That is why this method uses Degree of Authorship and review checks instead of raw counts.
• Never invent a handle, a team name, or an owner to complete a CODEOWNERS line. A visible gap beats a wrong route.
• Do not use the map to rank people. Bus factor measures how knowledge is spread across areas. Used as a league table of individuals, it punishes exactly the people carrying the most, and the data gets gamed within one cycle.
• Keep reruns comparable: same depth, same active window, same sensitivity list, unless a change is recorded in the notes.
• When the repository has almost no history, for example a new or freshly imported repo, say so and fall back to the worksheet filled in by the team. A precise looking map built on three commits is worse than an honest interview.