drift-check

Detect drift between the project's public API surface and its knowledge base (a docs/knowledge/ directory that names every public type and function).

When to use

• Before committing a change that adds, renames, or removes a public symbol.
• As a CI step that runs after every push.
• After a git pull if the upstream changed the public API.

Do not use this skill to scan private internals, generated code, or third-party dependencies. Its job is to keep the human-readable knowledge base honest about the public surface.

Inputs

Output

What counts as a public symbol

The skill uses a coarse regex; the precise rules are language-specific:

The skill is deliberately not a full parser. It trades false positives for a small, predictable rule set. If the regex does not match a deliberate public symbol, add it to baseline rather than fight the regex.

Algorithm (in three steps)

1. Extract public symbol names from the source tree using the language-specific regex.
2. Tokenise every file under knowledge_base into identifier-like tokens (alphanumerics and underscores).
3. Diff the symbol set against (knowledge base tokens ∪ baseline). Any symbol not present is drift.

Worked example (Swift)

Suppose Sources/CaffCore/SafetyPolicy.swift adds:

public struct SafetyPolicy {
    public func someNewMethod() { ... }
}

docs/knowledge/L1_modules.md does not mention someNewMethod.

Running drift-check with source_glob=Sources/CaffCore/*.swift and knowledge_base=docs/knowledge/ produces:

scanned 24 public symbol(s) across 9 file(s)
drift: 1 public symbol(s) not in L1_modules.md or baseline:
  - Sources/CaffCore/SafetyPolicy.swift:someNewMethod

The fix is to add someNewMethod to the L1 modules document. If it is genuinely not worth a knowledge-base entry, add someNewMethod to the baseline file.

Anti-patterns

• Running the skill on generated code. Generated code can change with every build, and its public surface is the generator's contract, not the project's. Exclude it from source_glob.
• Adding every internal helper to the baseline. The baseline is for symbols intentionally left out of the knowledge base, not for skipping the work. Use the knowledge base.
• Treating drift warnings as a code review substitute. The skill tells you the knowledge base is stale. It does not tell you whether the new symbol is well-designed.

Cross-references

• failure-classify — the next step in the loop. drift-check runs before the test, failure-classify runs after.
• init-loop — installs the script that this skill describes into a fresh project.
• drill — verifies that this skill actually reacts to a deliberately drifted commit.