Use when you are about to PROPOSE something to a young project or subproject — a design, a new capability, a discussion thread — and want to know why it is the way it is: who built it, what it was chosen over, what its authors already called incomplete, and which design arguments are still unresolved. Read the discussion arc that CREATED the repo before proposing to it. Its founding threads name the known-incomplete edges (so you don't report them as discoveries), the objections its own committers recorded (so you don't reopen them), and who actually cares about your area — none of which git history or CONTRIBUTING can tell you. For "does the ORIGINAL of this fork still have the same bug?" use port-the-report-upstream: that is code lineage, this is decision history. Trigger terms: new subproject, young repo, why does this exist, what did they already decide, project history, founding thread, VOTE thread, was this discussed before, prior discussion, before I propose, am I repeating something, is this wanted.
Read the project's origin story before you propose anything
Purpose
Code tells you what a project is. Its founding discussion tells you what it was
for, what it beat, what its own authors flagged as unfinished, and which arguments
were left open. That context is what separates a proposal a maintainer can act on from
one that re-litigates a settled decision or announces a gap the author declared
themselves.
The cost of skipping it is not just ignorance — it is confidently framing your work
wrong. A defect you present as a discovery may be a known consequence of a fast initial
port the author already warned about. A "missing capability" may be the exact thing the
project was chosen for, making your report far more significant than you pitched it.
Neither reading is available from the diff.
When to use
The repo is young, or is a subproject of a larger foundation project (a port counts,
but for a port's code lineage see port-the-report-upstream — this is its history).
You are about to propose a design, open a discussion thread, or frame a report as
"this is missing."
A maintainer invites you to "start another thread about that" — find out who has
already argued about it before you do.
You are writing the framing of work already done (an email, a PR body's Notes
section, a case study) and want the strongest true claim.
When NOT to use
Routine, self-contained bug fixes on a mature project. A one-line null guard does not
need the 2015 founding thread.
The project has no public discussion history (private origin, or a single-author repo
with no list). Then the README/CHANGELOG and the maintainer's own issues are the
substitute.
You are mid-incident and the fix is time-critical. Do it after.
The practice (checklist)
Find the threads that created the repo, not just the ones mentioning it.
Search the project's mailing-list archive / discussion forum by keyword over
months, not by the thread you are currently in. For ASF projects:
lists.apache.org/api/stats.lua?list=<list>&domain=<project>.apache.org&d=lte=180d&q=<keyword>
then thread.lua?id=<tid> then email.lua?id=<mid> per message.
Read the VOTE / proposal thread whole, including the +1s. Objections are
recorded inside approvals — "+1, but I'm skeptical we need X" is a live
disagreement wearing an approval.
Harvest four specific things and write them down:
1. What the authors said was incomplete. Founders describe their own MVPs
accurately. Anything they called WIP is a known edge, not your discovery.
2. What it was chosen over, and on what argument. That argument is the
project's purpose statement, and the strongest frame for work that serves it.
3. Unresolved objections — especially from committers who still voted +1.
These are tripwires; naming one shows you read, reopening it costs you.
4. Who wants what. Founders, the person who ran the vote, and the loudest
user usually want three different things.
Re-frame work you already did against what you found.Done when you can
state your contribution in the project's own founding terms rather than your own
— and you have checked whether that raises or lowers the claim.
Check whether the thing you are about to build already exists. Young projects
accumulate half-known tooling (guides, converters, scripts) that no one has
announced since the founding thread.
Route the proposal to everyone with standing, not just whoever invited you.
The person who asked may not be the person who owns the repo you'd touch.
Rationalizations
Shortcut
Why it fails
"I read CONTRIBUTING and the README, that's the documented context."
Those describe the current state. They do not record what was rejected, who objected, or what the author called unfinished — and those are the three things that determine whether a proposal lands.
"Git history tells me the project's story."
It tells you what changed, never why this project exists rather than the alternative. The tool-selection argument that defines the project's purpose happened on a list, months before the first commit.
"The maintainer invited me to propose it, so I have what I need."
The inviter is often not the owner of the affected repo, and may be the third-most-invested person in the topic. In the receipt below, the person who invited the thread had lost the original tool-selection argument; the two people who won it were never in my inbox.
"It's a young repo, there's barely any history to read."
Young repos have the most load-bearing history and the least code to infer it from — the founding thread is a larger fraction of everything knowable. 35 messages covered this project's entire existence.
"My finding stands on its own evidence, framing is cosmetic."
The same three defects can be "I found bugs in a new tool" or "the only variance mechanism in this tool's entire lineage was unreachable" — both true, one actionable. Framing is which true thing you say.
"I'll read the history if a maintainer pushes back."
By then you've already spent the first impression, and possibly reopened a settled question in public.
RECEIPT
SOURCING-receipt — a 35-message, 3-thread founding arc, read after 12 artifacts
were already filed, that changed the framing of all of them. Reconstructed 2026-07-27
from the ASF archive API; every item below is a verbatim quote from a message I read in
full.
Context: I had filed 6 issues + 6 PRs against apache/solr-orbit (a young ASF
subproject) and its upstream, based on running it. Only afterwards did I read the
Feb–May 2026 threads that created it. Four things I did not have:
The author had declared the incompleteness I "found." The tool's writer, in the
thread presenting it: *"I made a new effort using LLM agents and this first working
version was prepared in a few afternoons… view it as a MVP and WIP. Only one
workload / dataset is ported so far."* My three defects are the signature failure
of exactly that process, and the "missing workloads" gap I was about to report as a
finding was declared at birth.
What the project was chosen over — and the argument raised my claim. It won a
bake-off against a rival tool because the rival's "methodology for executing queries
/ drawing statistical conclusions leaves something to be desired (can expand in
detail if anyone wants to hear)" — an offer nobody took up. My work restored the
project's only variance-measurement mechanism. That reframes "I fixed three bugs"
into "I restored the capability this tool was selected for", which is the same
evidence making a materially bigger claim.
Two unresolved objections sitting inside +1 votes. Two committers approved while
recording doubt about a structural decision ("I'm skeptical we need a separate
'workloads' repository" / "I'm also unsure of having two separate repositories"),
and a third's renaming proposal was deferred to a follow-up vote that never
happened. Any proposal touching that structure walks into a live disagreement I'd
have had no idea existed.
The person who invited my proposal was the wrong sole recipient. A maintainer had
said "Let's start another thread about that!" — but the founding threads show he had
lost the original tool-selection argument, while the two people who mattered most
(the author who owns the affected repo and asked twice for contributors, and the
community member who ran the VOTE and chose the tool for that very capability) were
in neither my inbox nor my notes.
Also found by reading it: a workload-creation guide and an upstream→downstream
converter tool already existed in the repo, documenting exactly which constructs
convert automatically vs. need manual work. I had been about to propose work whose
mechanical half was already built.
The systematic sweep that missed all of it. The day before, I had run a
channel-complete status check — every PR via gh, every tracker issue via the project's
REST API, the mailing-list thread via the archive API — and it correctly reported that
nothing was waiting on me. It was clean and blind: it covered open items addressed to
me, not the domain the work sits in. Those are different questions.
track-whose-court answers the first; this skill answers
the second.
Lifecycle
Signals it worked: you can state your contribution in the project's own founding
language; you name a prior objection before a maintainer has to; you don't announce a
gap the authors already declared; your proposal reaches everyone with standing.
What to log on a misfire: what the founding threads said that you'd assumed the
opposite of, and whether it raised or lowered the claim you were about to make.
Record it in LEDGER.md.
Death criterion: none for young/ported projects. For a mature project with a
decade of history, the founding thread stops being load-bearing — read the recent
design discussions in the affected area instead.
1---2name: read-the-projects-origin-story3description: Use when you are about to PROPOSE something to a young project or subproject — a design, a new capability, a discussion thread — and want to know why it is the way it is: who built it, what it was chosen over, what its authors already called incomplete, and which design arguments are still unresolved. Read the discussion arc that CREATED the repo before proposing to it. Its founding threads name the known-incomplete edges (so you don't report them as discoveries), the objections its own committers recorded (so you don't reopen them), and who actually cares about your area — none of which git history or CONTRIBUTING can tell you. For "does the ORIGINAL of this fork still have the same bug?" use port-the-report-upstream: that is code lineage, this is decision history. Trigger terms: new subproject, young repo, why does this exist, what did they already decide, project history, founding thread, VOTE thread, was this discussed before, prior discussion, before I propose, am I repeating something, is this wanted.4---56# Read the project's origin story before you propose anything78## Purpose910Code tells you what a project *is*. Its founding discussion tells you what it was11*for*, what it beat, what its own authors flagged as unfinished, and which arguments12were left open. That context is what separates a proposal a maintainer can act on from13one that re-litigates a settled decision or announces a gap the author declared14themselves.1516The cost of skipping it is not just ignorance — it is confidently framing your work17wrong. A defect you present as a discovery may be a known consequence of a fast initial18port the author already warned about. A "missing capability" may be the exact thing the19project was chosen *for*, making your report far more significant than you pitched it.20Neither reading is available from the diff.2122## When to use2324- The repo is young, or is a subproject of a larger foundation project (a port counts,25 but for a port's *code* lineage see port-the-report-upstream — this is its history).26- You are about to propose a design, open a discussion thread, or frame a report as27 "this is missing."28- A maintainer invites you to "start another thread about that" — find out who has29 already argued about it before you do.30- You are writing the *framing* of work already done (an email, a PR body's Notes31 section, a case study) and want the strongest true claim.3233## When NOT to use3435- Routine, self-contained bug fixes on a mature project. A one-line null guard does not36 need the 2015 founding thread.37- The project has no public discussion history (private origin, or a single-author repo38 with no list). Then the README/CHANGELOG and the maintainer's own issues are the39 substitute.40- You are mid-incident and the fix is time-critical. Do it after.4142## The practice (checklist)4344- [ ] **Find the threads that created the repo, not just the ones mentioning it.**45 Search the project's mailing-list archive / discussion forum by keyword over46 months, not by the thread you are currently in. For ASF projects:47 `lists.apache.org/api/stats.lua?list=<list>&domain=<project>.apache.org&d=lte=180d&q=<keyword>`48 then `thread.lua?id=<tid>` then `email.lua?id=<mid>` per message.49- [ ] **Read the VOTE / proposal thread whole**, including the +1s. Objections are50 recorded *inside* approvals — "+1, but I'm skeptical we need X" is a live51 disagreement wearing an approval.52- [ ] **Harvest four specific things** and write them down:53 1. **What the authors said was incomplete.** Founders describe their own MVPs54 accurately. Anything they called WIP is a known edge, not your discovery.55 2. **What it was chosen over, and on what argument.** That argument is the56 project's purpose statement, and the strongest frame for work that serves it.57 3. **Unresolved objections** — especially from committers who still voted +1.58 These are tripwires; naming one shows you read, reopening it costs you.59 4. **Who wants what.** Founders, the person who ran the vote, and the loudest60 user usually want three different things.61- [ ] **Re-frame work you already did against what you found.** *Done when* you can62 state your contribution in the project's own founding terms rather than your own63 — and you have checked whether that raises or lowers the claim.64- [ ] **Check whether the thing you are about to build already exists.** Young projects65 accumulate half-known tooling (guides, converters, scripts) that no one has66 announced since the founding thread.67- [ ] **Route the proposal to everyone with standing**, not just whoever invited you.68 The person who asked may not be the person who owns the repo you'd touch.6970## Rationalizations7172| Shortcut | Why it fails |73|---|---|74| "I read CONTRIBUTING and the README, that's the documented context." | Those describe the current state. They do not record what was rejected, who objected, or what the author called unfinished — and those are the three things that determine whether a proposal lands. |75| "Git history tells me the project's story." | It tells you what changed, never why this project exists rather than the alternative. The tool-selection argument that defines the project's purpose happened on a list, months before the first commit. |76| "The maintainer invited me to propose it, so I have what I need." | The inviter is often not the owner of the affected repo, and may be the third-most-invested person in the topic. In the receipt below, the person who invited the thread had *lost* the original tool-selection argument; the two people who won it were never in my inbox. |77| "It's a young repo, there's barely any history to read." | Young repos have the *most* load-bearing history and the least code to infer it from — the founding thread is a larger fraction of everything knowable. 35 messages covered this project's entire existence. |78| "My finding stands on its own evidence, framing is cosmetic." | The same three defects can be "I found bugs in a new tool" or "the only variance mechanism in this tool's entire lineage was unreachable" — both true, one actionable. Framing is which true thing you say. |79| "I'll read the history if a maintainer pushes back." | By then you've already spent the first impression, and possibly reopened a settled question in public. |8081## RECEIPT8283***SOURCING-receipt*** — **a 35-message, 3-thread founding arc, read *after* 12 artifacts84were already filed, that changed the framing of all of them.** Reconstructed 2026-07-2785from the ASF archive API; every item below is a verbatim quote from a message I read in86full.8788Context: I had filed 6 issues + 6 PRs against `apache/solr-orbit` (a young ASF89subproject) and its upstream, based on running it. Only afterwards did I read the90Feb–May 2026 threads that created it. Four things I did not have:91921. **The author had declared the incompleteness I "found."** The tool's writer, in the93 thread presenting it: *"I made a new effort using LLM agents and this first working94 version was prepared in a few afternoons… view it as a MVP and WIP. **Only one95 workload / dataset is ported so far.**"* My three defects are the signature failure96 of exactly that process, and the "missing workloads" gap I was about to report as a97 finding was **declared at birth**.982. **What the project was chosen over — and the argument raised my claim.** It won a99 bake-off against a rival tool because the rival's *"methodology for executing queries100 / drawing statistical conclusions leaves something to be desired (can expand in101 detail if anyone wants to hear)"* — an offer **nobody took up**. My work restored the102 project's only variance-measurement mechanism. That reframes "I fixed three bugs"103 into "I restored the capability this tool was selected for", which is the same104 evidence making a materially bigger claim.1053. **Two unresolved objections sitting inside +1 votes.** Two committers approved while106 recording doubt about a structural decision (*"I'm skeptical we need a separate107 'workloads' repository"* / *"I'm also unsure of having two separate repositories"*),108 and a third's renaming proposal was deferred to a follow-up vote **that never109 happened**. Any proposal touching that structure walks into a live disagreement I'd110 have had no idea existed.1114. **The person who invited my proposal was the wrong sole recipient.** A maintainer had112 said *"Let's start another thread about that!"* — but the founding threads show he had113 *lost* the original tool-selection argument, while the two people who mattered most114 (the author who owns the affected repo and asked twice for contributors, and the115 community member who ran the VOTE and chose the tool for that very capability) were116 in neither my inbox nor my notes.117118**Also found by reading it:** a workload-creation guide and an upstream→downstream119**converter tool** already existed in the repo, documenting exactly which constructs120convert automatically vs. need manual work. I had been about to propose work whose121mechanical half was already built.122123**The systematic sweep that missed all of it.** The day before, I had run a124channel-complete status check — every PR via `gh`, every tracker issue via the project's125REST API, the mailing-list thread via the archive API — and it correctly reported that126nothing was waiting on me. It was clean *and* blind: it covered open items addressed to127me, not the domain the work sits in. Those are different questions.128[track-whose-court](../track-whose-court/SKILL.md) answers the first; this skill answers129the second.130131## Lifecycle132133- **Signals it worked:** you can state your contribution in the project's own founding134 language; you name a prior objection before a maintainer has to; you don't announce a135 gap the authors already declared; your proposal reaches everyone with standing.136- **What to log on a misfire:** what the founding threads said that you'd assumed the137 opposite of, and whether it raised or lowered the claim you were about to make.138 Record it in [`LEDGER.md`](../../LEDGER.md).139- **Death criterion:** none for young/ported projects. For a mature project with a140 decade of history, the founding thread stops being load-bearing — read the recent141 design discussions in the affected area instead.142- **Relates to:** [use-the-tool-for-its-purpose](../use-the-tool-for-its-purpose/SKILL.md)143 finds the defect, this explains why it was there and what it's worth;144 [port-the-report-upstream](../port-the-report-upstream/SKILL.md) is the same145 "understand the lineage" instinct applied to code rather than history;146 [consolidate-a-scattered-thread](../consolidate-a-scattered-thread/SKILL.md) traverses147 a live discussion, this one excavates a settled one;148 [track-whose-court](../track-whose-court/SKILL.md) is the sweep this is NOT a149 substitute for, and vice versa.
Run npx skillmds@latest add serhiy-bzhezytskyy/read-the-projects-origin-story in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Use when you are about to PROPOSE something to a young project or subproject — a design, a new capability, a discussion thread — and want to know why it is the way it is: who built it, what it was chosen over, what its authors already called incomplete, and which design arguments are still unresolved. Read the discussion arc that CREATED the repo before proposing to it. Its founding threads name the known-incomplete edges (so you don't report them as discoveries), the objections its own committers recorded (so you don't reopen them), and who actually cares about your area — none of which git history or CONTRIBUTING can tell you. For "does the ORIGINAL of this fork still have the same bug?" use port-the-report-upstream: that is code lineage, this is decision history. Trigger terms: new subproject, young repo, why does this exist, what did they already decide, project history, founding thread, VOTE thread, was this discussed before, prior discussion, before I propose, am I repeating something, is this wanted. It is listed under Docs & Writing on SkillMD.
This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
serhiy-bzhezytskyy (@serhiy-bzhezytskyy) published this skill. Their other Agent Skills are listed on their SkillMD profile.
serhiy-bzhezytskyy