Docs Context Mapping and Quickstart Testing
- this is a good idea, how are you mapping docs context to the actual app commits.
this is assuming - docs live in the app reposiotory itself ? 2. also, claude/codex can do this - you can get this question a lot. How would you answer this
I got this question how do i answer? Fast on short.
Q1: How do you map docs to commits?
Send this:
By topic and by date, not by a hard link. firstrun reads the git history once. It pulls a topic word from each product commit (the scope, like
fix(auth):, and the changed paths). It matches those words to doc pages. A page is stale when commits on its topic landed after the page's last edit. A topic with many commits and no page is a "no docs" gap.Docs in a separate repo work too. It reads the code repo for commits and the docs repo for pages, then joins them on topic and date. So the docs do not have to live in the app repo.
The limit: it is a heuristic. A commit with no clear scope or topic gets sorted by a small model call, and it can miss.
Q2: Claude and Codex can do this.
Send this:
Yes, they can read a repo and guess what is stale. firstrun does not guess, it runs the docs.
- It follows your quickstart in a clean environment, like a new user.
- It finds the exact step that fails.
- It bisects to the commit that broke it.
- It runs on a schedule and logs every run in public, so you can check it.
Claude can tell you a page looks old. firstrun shows you that step 3 fails today, and which commit caused it. You could build this on Claude or Codex. firstrun is that work, already done and running.
Check before you send: I confirmed the mapping from src/firstrun/audit.py. The run, bisect and public log claims in Q2 come from the file names (executor.py, bisect.py) and your run log commit. Confirm they match how you describe the tool.
Next: tell me if you want either reply cut to two lines.
make it two lines each
Q1: How do you map docs to commits?
By topic and date. It reads the git history once, pulls a topic from each commit's scope and changed paths, and flags a page as stale when commits on its topic land after its last edit. Docs can live in a separate repo: it reads code commits from one and pages from the other, then joins on topic.
Q2: Claude and Codex can do this.
They can guess a page looks old. firstrun runs your quickstart in a clean environment, finds the step that fails, and bisects to the commit that broke it. It runs on a schedule and logs every run in public, so you see proof, not an opinion.