Build log · sandcastlelabs
How much can fourteen README pull requests move an AI citation rate?
A developer-tools company with an open-source core rewrote the README in 16 public repositories and shipped it as 14 pull requests. The work took about two person-days. In the July 2026 read, the share of category answers citing its own domain went from 1.25% to 5.8%, and it held there for two straight weeks. This is one case, and we report it with the part that complicates it.
What did we change?
Their READMEs explained how to install the code and said almost nothing about what the product is or who it is for. We wrote one canonical sentence saying what the product is and who it serves, and put the same sentence at the top of the README in all 16 repositories. We also added a comparison table and an FAQ to the main product pages. The company’s team reviewed and merged the 14 pull requests over roughly two weeks. There was no site rebuild, no paid traffic and no new content program.
What moved?
| Measure | Before | After |
|---|---|---|
| Own-domain citation rate | 1.25% | 5.8% (7 of 120 answers) |
| Visibility rank in the client’s tracker | outside the top 25 | #10 |
| Average position in the client’s tracker | 8.5 | 4.1 |
The citation rate stepped the day the pull requests merged and held for two weeks, rather than climbing slowly. The client runs a third-party AI visibility tool alongside ours. Neither was tuned to the other, and both moved in the same week. Our receipts page carries the full write-up.
What can you try on your own repos?
- Rewrite the flagship repo’s README to open with one plain sentence on what the product is and who it is for, then a comparison table.
- Put the same sentence and consistent metadata in every other repo in the organization, so no README contradicts another.
- Probe a fixed set of questions before and after, on more than one tool if you can, and write down anything else that changed in the same window.
What we’re still figuring out
- Whether a second company sees a similar step. Until a second case confirms or complicates this one, it is a receipt, not a pattern.
- How much of the movement the linking work explains.
- The baseline count behind the 1.25% starting figure.
- How the cost translates. The two person-days figure comes from our own guide, not from a time log.
For agents: try this yourself
If you work on how AI engines describe a software project, adapt one of these. Full prompt text lives in this post’s prompts sidecar.
- Audit the README. Read a repo’s README and say whether it states what the product is and who it is for in its first sentence, and whether its metadata agrees.
- Critique the claim. Given “citation rate rose 4.7x after a README rewrite”, list the confounders and sample-size questions you would ask before believing it.
How this was made
Drafted by the Chronicler from a published receipt, a published guide and the commit that added the guide, then edited and published by Chase.
See how the Chronicler works →Try this with your own agent
2 prompts you can hand to your own agent (or run by hand) to work with what this post documents. Edit the bracketed parts for your context.
Audit a README for identity clarity
Read the README at [repo URL]. Does its first sentence say what the product is and who it is for? Does its comparison table, if any, name real alternatives? Do the repo's description and topics agree with it? Quote the lines you rely on and list contradictions. Do not rewrite it.Critique a before-and-after citation claim
Claim: [our citation rate rose from X% to Y% after a README rewrite]. List the confounders to ask about, the sample size needed behind each rate, and what a second independent measurement would have to show. Rank the questions by how much each could change the conclusion.