Standing service test-keep-tests-and-docs-current-each-month · revised 11 October 2026
Standing service
Keep tests and documentation matching what your code now does, each month
When behaviour changes on your default branch, we open a pull request that updates the tests and the README or docs to match, up to an agreed number a month, with a monthly drift report.
This starts a conversation by email. Nothing is charged, and nothing is monitored, until we have agreed scope and terms with you in writing.
The responsibility you hand over
Tests and documentation drift from the code one small change at a time: a function gains a parameter, a command is renamed, a setting is added. Nobody owns the upkeep, so tests pin old behaviour or are missing for new behaviour, and the README sends readers down steps that fail. A standing responsibility keeps both in step with what the code now does.
Who it’s for: A founder or engineering lead whose tests and documentation matched the code at launch and have drifted since, with nobody assigned to keep them in step.
Usually starts when: A new developer followed the README and could not get the project to run, a test passes while describing behaviour that no longer exists, or a changed command or setting is mentioned nowhere.
The result: After a behaviour change merges on the named repository, a follow-up pull request brings its tests and documentation into line, up to the agreed monthly number, and each month a drift report shows what was found stale, what was updated and what is still open.
What stays true, and what we do about it
No response-time guarantee is published for this new service. A target for how soon a follow-up pull request is opened is agreed in writing before it starts, set to what a service at this stage can actually keep.
Hours are agreed in writing before the service starts. At launch the service is not staffed round the clock, so we do not offer out-of-hours cover.
What must remain true
- The documented setup, run and test commands still work on a clean environment
- Each behaviour change merged on the default branch has tests and documentation that describe it, or is listed as open in the drift report
What we watch
- Merged pull requests and commits on the default branch, read through a read-only account you create
- The monthly run of the documented commands on a clean environment
When something happens
Scroll the table sideways to read it all.
| When | What we do |
|---|---|
| A change that alters behaviour, a command, a configuration value or a public interface is merged on the default branch. | We read the change, open a follow-up pull request that updates its tests and the documentation that describes it, and run the suite. |
| The monthly clean-environment run of the documented commands fails. | We find the step that no longer works, correct the instructions in a pull request, and say in the report what changed. |
| A month ends. | We send the drift report: changes seen, pull requests opened, stale items still open and the decisions they need from you. |
We do on our own
- Read merged changes and run the tests and documented commands on a clean environment
- Open pull requests that change tests and documentation
- Ask your named person what a change was meant to do
We ask you first
- Changing production code, even to make a test pass
- Removing or loosening an existing test
- Anything that touches secrets, repository settings or deployment
We escalate to you when
- An updated test shows a defect or a behaviour that contradicts the documentation
- A change is too large to document in one follow-up pull request
- Merged changes regularly pass the agreed monthly number
How you know it held. Each month the drift report lists every merged change seen, the follow-up pull request for it or the reason there is none, and the result of the clean-environment run, so you can compare it with your own merge history.
How we keep it true
This service is never finished. Each month's drift report shows whether tests and documentation stayed in step, and it continues until you end it.
A README and setup guide proven by a cold start on a clean machine Job First
The setup guide for one repository is rewritten and then followed on a clean machine until the project runs and its tests pass. Every command you read in it has been run.
If the README fails a clean-environment run when the service starts, the one-off cold-start job gives it a working baseline first.
Pin one module's current behaviour with a regression test suite Job Optional
A test suite around one named module records what it does today, so a refactor or upgrade shows exactly which behaviour changed. You get the tests, a seeded-change check and a gaps note.
For a module that changes often and has no tests at all, the one-off regression suite is a better first step than patching tests one change at a time.
What is included, and what is not
- A follow-up pull request for each qualifying change within the agreed number, with its tests and documentation edits
- The monthly clean-environment check result: each documented command, whether it worked and what was changed to fix the instructions
- The monthly drift report, listing open stale items and the decision each needs from you
Included
- One repository's default branch, and changes that alter behaviour, a command, a configuration value or a public interface
- For each qualifying merged change, up to four a month or another number agreed in writing, a follow-up pull request that adds or updates tests for the changed behaviour and updates the documentation that describes it
- Each month, run the documented setup and test commands on a clean environment and report what no longer works
- A monthly drift report: changes seen, tests and documentation updated, stale items found and still open
Not included
- New features, refactoring or fixing defects the updated tests reveal; each defect is a separate bug-fix job
- Documentation of areas that did not change, user manuals, marketing copy or architecture documents
- A coverage percentage target
- Merging, deploying or changing repository settings
- Out-of-hours cover or any guaranteed response time
How we know it’s done
Agreed with you before work starts. Each check produces evidence you keep.
For each qualifying change within the agreed number, a follow-up pull request exists whose new or updated tests pass on the current code and fail when run against the revision from before the change, or the report states why such a test was not possible.
Evidence: The pull request with the test results on the current revision and on the earlier revision, or the reason in the report.
Each monthly report lists the result of every documented setup and test command on a clean environment, with the fix for any that failed.
Evidence: The monthly clean-environment record and the pull requests that corrected the instructions.
No existing test is removed or loosened and no production code is changed without your written approval.
Evidence: The pull request diffs, reviewed by a second reviewer, and your approvals.
Sign-off. You review and merge each pull request and read each monthly report. A follow-up counts as delivered when you accept it.
If it fails. If we cannot bring a change's tests or documentation into line, we say so, explain what we found and what it would take, and it does not count against the monthly number. If the service is not working for you, you can end it at the end of any month.
When it fits, and when we stop
It fits when
- The repository has a test runner that passes today, and a README whose setup and test commands can run on a clean environment with invented configuration values
- A read-only token or account for merged changes, and a fork or branch from which we can open pull requests
- A person on your side reviews and merges pull requests and answers questions about intended behaviour
We stop and tell you if
- The test suite fails or is flaky when we start: we say so and suggest repairing it before the service begins
- Changes regularly exceed the agreed monthly number, so follow-ups would fall behind: we agree a different scope
- Nobody reviews the follow-up pull requests for two months in a row, so the drift report only grows
What could go wrong
Every follow-up is a pull request that your team merges, so you can revert it like any other change. Ending the service leaves your repository as it is, with open pull requests finished or handed back.
Scroll the table sideways to read it all.
| Risk | How we handle it |
|---|---|
| Updated tests are written to match whatever the code does, so they bless a defect. | Where a test would pin behaviour that contradicts the documentation or the stated intent, we escalate to your named person instead of recording it as correct. |
| Documentation is updated without being run, so it is wrong in a new way. | Documented commands are run in the clean-environment check and in each follow-up that edits them. |
| A follow-up weakens an existing test to get a pass. | Removing or loosening a test needs your approval, and the reviewer checks each diff for it. |
A second reviewer checks a sample of follow-up pull requests each month for tests that could not fail and documentation that was not run. No human supervisor is included unless your agreement names one. At launch the work is largely automated, and we say so.
Stays with a person
- You review and merge every pull request
- You approve any change to production code, removed tests, secrets or settings
Access we would need
- A read-only token for merged changes on the default branch
- Access to a fork or branch for pull requests
Questions
How is this different from fixing the README once?
A one-off job proves the setup guide on a clean machine at one point in time. This service keeps tests and documentation in step with each behaviour change afterwards, and repeats the clean-environment check every month.
Will you change the code when a test fails?
No. Production code changes need your approval. If an updated test shows a defect, we report it to your named person and it is handled as a separate job.
What counts as a qualifying change?
A merge that changes behaviour, a command, a configuration value or a public interface. Pure refactors and unrelated fixes that keep behaviour the same do not need new tests or documentation.
Send an enquiry
Send us
- The repository's platform, language and framework in general terms, and roughly how many behaviour-changing merges a month it gets
- Whether the README setup commands work today (yes, no or not sure)
- Who reviews and merges pull requests and who can say what a change was meant to do
- Do not send code, credentials or an access invitation in the first enquiry
Later, once you agree
- A read-only token or account limited to merged changes on the default branch
- Access to a fork or branch from which we can open pull requests
- The agreed monthly number, the person to ask about intent and the invented configuration values for the clean-environment check
Your repository, secrets and merge decisions stay yours. We read merged changes with a read-only account you create, and we change files only on a branch or fork, through pull requests your team reviews and merges. We do not deploy or change repository settings.
Email fallback: open your mail app
If website submission is unavailable, review and send the fallback email yourself. An email fallback is not a website receipt. Or write to hello@syntheticindustry.ai with “test-keep-tests-and-docs-current-each-month” as the subject.