Engineering principles extracted from your actual commits, not your handbook

Every engineering team has two sets of principles.

The first set is in the handbook — CONTRIBUTING.md, the onboarding doc, the engineering blog post from 2021 that someone still links in Slack. These describe the team as it intended to operate. They were written in a good moment, by people thinking carefully about what good engineering looks like.

The second set is in the commit history. These describe the team as it actually operates. They're implicit — expressed in the choices engineers make under deadline pressure, in the patterns that recur across 200 pull requests, in the decisions that became conventions because they worked. Nobody wrote them down. They're real anyway.

The gap between these two sets of principles is where new engineers make avoidable mistakes, where AI coding agents operate without guardrails, and where code review becomes inconsistent because different reviewers are enforcing different mental models of what the team actually does.

What extraction looks like

The Skill Transfer system runs in two phases.

Phase 1 captures behavioral patterns from engineering sessions: prompt patterns, recurring decision structures, the "if this, then that" logic that appears repeatedly across a team member's sessions. The capture substrate identifies candidates — moments in sessions where a clear, repeatable pattern is present.

Phase 2 runs an LLM extraction pipeline over the captured patterns. Candidates are formalized into structured skills: natural language descriptions of the pattern, the conditions under which it applies, and the evidence base (how many times it appeared, across how many sessions or PRs).

The output is visible in the Intelligence tab under Skills. A team lead reviews the extracted skills before they're promoted to the active set. Some get promoted as-is. Some get edited — the extractor may have over-generalized, or captured a pattern that applies to one module but not universally. Some get discarded. The review step is part of the model; extraction is a first pass, not a final judgment.

The kinds of principles that emerge

Not abstractions — specific, testable patterns.

From 47 PRs touching the API layer:

When adding a new endpoint, this team includes an integration test and a contract test — not just a unit test. Unit tests are not sufficient for new routes.

From 23 PRs involving the billing module:

Changes to the billing module get a [billing] tag in the PR and a ping to #billing-reviews before merge. This has been consistent since the Q3 2025 incident.

From 12 migrations:

When a migration adds a NOT NULL column, the team always includes a backfill default in the same migration. Separate backfill migrations have caused issues twice.

From 18 async tasks:

Every async write path gets a timeout at the operation level (not just the HTTP timeout) and a per-user single-flight gate. This was established after a production incident in early 2026.

None of these are in the CONTRIBUTING.md. All of them are real. All of them are the kind of thing a reviewer would say to a new engineer — "we don't do it that way here" — if they happened to know.

Where extracted principles go

Once promoted, principles are stored as memories in Memory Stack, tagged for the contexts where they apply. A principle tagged for the billing module surfaces when someone opens a PR that touches that module. A principle tagged for async write paths surfaces when someone adds a new async operation.

This is the code-review-context flow described in a companion post. The two systems work together: extraction generates the principles from observed behavior; tagging makes them available at the point where they're relevant.

The extraction pipeline is also generative: as the team continues operating, new patterns emerge. An approach the team settled on this quarter becomes a principle next quarter. The system doesn't require anyone to decide "this is now official" — the pattern just becomes observable in the data, and the next extraction pass surfaces it.

Why this matters for AI coding agents

A CONTRIBUTING.md is a document that AI agents can read. It's also static, usually outdated, and describes ideal behavior rather than actual behavior.

Extracted engineering principles are the actual behavior — current, attributed, evidence-based. When a coding agent is working in a codebase with a rich Memory Stack integration, the principles it operates under aren't "what the handbook says" — they're what this team actually does, updated as the team's behavior evolves.

The result is an agent that operates with genuine team context, not generic software engineering principles. It knows that this team treats billing module changes with a specific review process. It knows that async writes require the gate. It knows about the migration convention because the evidence is there.

The honest version

Extraction is not perfect. The pipeline makes mistakes — patterns that aren't really patterns, generalizations that don't hold across the full codebase. The Skills review queue exists because promoted skills need human validation before they're active.

Extraction quality also scales with input quality. A team with sparse commit discipline, inconsistent PR descriptions, and irregular review patterns will generate weaker extraction candidates. The system reflects the quality of the engineering process it's learning from. If your commits are "fix stuff" and your PRs have no description, the extractor has little signal to work with.

And the extracted principles don't replace explicit decision logging. A critical architectural decision made in a meeting — "we're moving to event sourcing for the order service" — should be logged explicitly, not left to be inferred later. The extractor is a complement to explicit capture, not a substitute for it. High-stakes, binding decisions belong in the explicit capture layer.

The gap between your handbook and your commit history is where your team's real principles live. Those principles are now extractable, reviewable, and loadable — by the humans and AI agents working in your codebase.