totem_skill

Overview

This skill profiles a project's implicit culture across eight dimensions (Naming, Abstraction, Error Handling, Comments, Testing, Architecture, Git, Dependencies). It detects deviations in new code or PRs against that DNA and generates concise onboarding guides that transfer unwritten norms to new contributors. Totem never writes or changes code; it discovers, scores, and describes the project's voice so teams can act with context.

How this skill works

Totem samples a statistically meaningful portion of the codebase, git history, configs, and tests to extract dominant patterns and occurrence rates for each of the eight dimensions. It scores each dimension 0–3 with evidence percentages, flags module subcultures and confidence levels, and classifies deviations as HIGH/MEDIUM/LOW/INFO. Outputs include a Cultural Fingerprint (one-paragraph summary), a full DNA Profile, deviation reports for PRs, and onboarding guides derived from the profile.

When to use it

• You want to make implicit team conventions explicit before a major refactor or standardization effort.
• You need culture-aware context added to code reviews so reviewers can weigh deviations appropriately.
• Onboarding new contributors quickly by showing project-specific naming, testing, and commit conventions.
• Monitoring cultural drift over time after multiple contributors or a large influx of external patches.
• Before creating linter rules or automation: discover which implicit rules are actually practiced.

Best practices

• Sample a statistically meaningful set of files (recommended ≥30 files or ≥20% of codebase) before profiling.
• Always include confidence and evidence percentages for each dimension; flag low-confidence dimensions explicitly.
• Exclude generated, vendored, or fixture code and treat module subcultures as scoped exceptions.
• Use git blame and PR context to distinguish intentional evolution from accidental deviation.
• Provide actionable guidance alongside deviations (what to change, what to ignore, how to escalate).

Example use cases

• Generate a DNA Profile to guide culturally aligned refactoring proposals from a proposed design change.
• Run automatic deviation checks on inbound PRs and annotate reviews with cultural context for maintainers.
• Produce an onboarding guide that summarizes naming conventions, test philosophy, commit style, and common idioms.
• Track how a dimension (e.g., Testing) drifts over time after shifting team composition or tech stacks.
• Convert discovered conventions into guardable artifacts (briefs for review tools or conventions to formalize).