01.1The internship problem

At the beginning of my internship I was assigned older projects that had not been maintained particularly well. Before I could contribute, I first had to reconstruct what the project was, how it worked, why it looked the way it did and what had changed before I arrived.

The frustrating part was that Git history existed. The information was technically present, but not in a form that helped a new or returning developer understand the project quickly.

01.2Three different context moments

I started thinking about developer context as three related but different moments.

Those moments need different levels of detail, but they can all be built from the same preserved history if context is captured continuously.

01.3The success condition

The goal was not to create another documentation dashboard. I wanted context to live close to the repository and be updated as work happened.

A developer returning after time away should be able to understand the important changes without manually reading every file and every commit. A new developer should be able to get an architecture and decision overview without depending on someone who still remembers the project.

02.1The first version was heavier than the problem

The first architecture used DSPy and Gemini, LangGraph and ChromaDB. At that stage I was still exploring both the problem and the frameworks, so a more agentic/vector-heavy architecture seemed reasonable.

Once I understood the workflow better, it felt overbuilt. I did not need a vector database to rediscover which commit changed a file. I did not need a graph framework to determine a commit range.

That realization became the most important architecture change in the project.

02.2Let Git do deterministic work

Git already knows who changed something, when they changed it, which commits are relevant and what the exact diff is. Checkpoint therefore lets Git handle those facts and sends only the context that still needs interpretation to the model.

That makes the model input smaller and the behaviour easier to reason about. The model explains change; it does not reconstruct version control.

The best architecture was not the one with the most AI in it.

02.3Why Markdown became the memory layer

The generated context is stored as Markdown in the repository. That was deliberate. A developer can open it without another tool, Git can version it, a pull request can review it and a future model can consume the same file as context.

That gives me one source of project context that is readable by both people and models instead of separate human docs and machine memory.

02.4Why GitHub Actions became the default trigger

The project initially supported local hooks, but GitHub Actions became the natural primary path because the development events already happen there. A push, PR or merge is the moment context should be captured.

That also removes a behavioural dependency on the developer remembering to run a command. The workflow can derive the relevant commit range, generate the context artifact and commit the result back into the repository.

The difficult edge is making sure the automation does not summarize its own generated files or bot-authored commits and create a feedback loop.

02.5Keep model choice configurable

The later architecture uses LiteLLM so the model layer is not hard-coded to one provider. Mistral was the model I used in practice, but the case study is not a claim that every provider was tested equally.

The useful abstraction is that Git/context preparation is stable while the interpretation model can be changed through configuration.

03.1Commit checkpoints

On a push, the workflow derives the human commit range, filters bot/config-only work, gets the deterministic diff and metadata, and sends the bounded change context to the Checkpoint generator.

The generated checkpoint is prepended to a stable per-author Markdown file. The checkpoint is the smallest unit in the system: a dated explanation of what changed at that moment and why it matters.

Generated Checkpoint paths are excluded from the diff so the tool does not continuously summarize itself.

03.2Personalized catch-up

Catch-up starts from a developer rather than a commit. The system finds that developer's last activity, reads checkpoint entries since then and excludes the requesting author's own changes.

That produces a briefing of what other people changed while the developer was away. When the developer contributes again, the stale catch-up can be removed because the context gap has closed.

Some of the trickier bugs here were ordinary temporal edge cases - identity, self-inclusion and date/timezone behaviour - rather than dramatic AI failures.

03.3PR summaries

For pull requests, Checkpoint combines PR metadata, the base-to-head diff and the commit-level checkpoint walkthrough into a higher-level review artifact.

The goal is to give a reviewer architectural impact, important changes and review context without losing the connection to the individual commits underneath.

I do not claim a measured review-time reduction; the value here is the implemented workflow and the structure of the context it preserves.

03.4Master Context for onboarding

The onboarding path builds a broader project view. It can combine the repository tree, recent checkpoints, README/dependency context and generated architecture diagrams into MASTER_CONTEXT.md.

For Python projects, some diagrams can be produced deterministically from AST analysis. For multi-language projects, selected files can be passed to the model for a language-agnostic diagram. The point is orientation, not perfect reverse-engineering.

This artifact is the answer to the original internship problem: a new developer gets the project mission, architecture, decisions, gotchas and starting point without reconstructing everything manually.

03.5From experiment to installable tool

Checkpoint was published to PyPI as checkpoint-agent, with a setup guide and GitHub Actions templates. That forced the project to become more than a repo-specific experiment: configuration, packaging, release workflows and backwards compatibility all became part of the product.

The release workflow builds the package, verifies the version and uses trusted publishing rather than embedding long-lived PyPI credentials.

03.6Observed workflow optimization

I also went back through the GitHub Actions history around the 29fd5bf "Optimised Checkpoints" period to get a defensible runtime comparison.

04.1What worked

I used Checkpoint myself during its initial development. The automatic checkpoint, catch-up, PR summary and onboarding/master-context flows worked, and the package was published to PyPI.

That is the result I am comfortable presenting: a working developer-context tool with repository-native artifacts and automated GitHub workflows.

04.2How I judged the output

The generated Markdown was meant for humans, so I judged it by reading it. I looked for whether the explanation was useful, whether it reflected the real diff and whether the document made the repository easier to understand.

There was no formal evaluation dataset or quality harness. I do not claim factuality scores or measured onboarding-time savings.

04.3Current status

The project is paused, with a working core. The newest work was moving toward support for cloud-hosted repository environments, including Azure/GCP/AWS-shaped workflows, but that path has not been fully tested.

I still want to finish it. The pause is a project-state description, not a claim that the earlier workflows stopped working.

04.4What I learned

Checkpoint is where I learned a principle that shows up in my newer projects too: deterministic systems should do deterministic work, and models should be used where interpretation is actually useful.

It also changed how I think about AI memory. The most useful memory is often not a hidden vector store. Sometimes it is a clear, versioned artifact that a human can read and a model can reuse.

Context is more useful when it is preserved as part of the work, not reconstructed after the fact.

04.5Next

When I return to Checkpoint, the roadmap is focused: finish cloud-hosted repository support, add Bitbucket, add configurable sensitive-context controls for files/paths/patterns/content, and experiment with Simplified Technical English as a writing standard for generated documentation.

The STE direction is especially interesting to me because the output should read like project documentation, not generic AI prose. I would treat formal ASD-STE100 compliance as a separate future validation question rather than claim it today.