pythia-conventions

Adopting a Project's Conventions

Announce at start: "Using pythia-conventions — I'll read the patterns off the schema first."

Phase: Learn → Ask — derive from the schema, ask where the document disagrees, only then write the config

Conventions already exist in every mature schema. They are in the object names, in a standards document, or in a senior developer's head. This turns them into two files: patterns the tool checks on every write, and prose every future agent session reads before writing.

The Iron Law

NO PATTERN WRITTEN DOWN BEFORE THE SCHEMA HAS AGREED WITH IT

A pattern that does not match the objects already there is not a convention. It is a guess that will warn on every apply until someone deletes it.

The Workflow

1. Read the shape off the database, not off your memory of it.

   pythia conventions --scan
   

   It tokenises every object name and proposes a pattern per type. Do this even when a document exists — and never page through thousands of names yourself: that is what the command is for, and your context is better spent elsewhere.

2. Read the developer's document, if there is one. A base system's standards, a wiki page, an older project's rules. Look for what a regex cannot hold: parameter prefixes a calling layer depends on, a column every query must filter by, where a transaction may commit, which date or money representation is canonical. Those go in the prose half.

3. Reconcile, and say so when the two disagree. The document states intent; the schema states fact. A rule in the document that the schema contradicts is one of three things — a rule nobody follows, a rule for new code only, or drift worth reporting. Ask the developer which; do not silently pick.

4. Write .pythia/conventions.json. Start from the scan output, narrowed by the document. pythia conventions --init writes a blank pair if you want the skeleton first.

5. Verify — this step is the point of the skill.

   pythia conventions --check
   

   It reports coverage per type and names what misses.

   Result	What it means
   every name matches	the pattern is real; keep it
   ~90%+ with a handful of misses	genuine exceptions — list them in step 6
   below 90%	the pattern is wrong, not the schema; widen or split it, then check again
   nothing of that type	an untested rule; keep it only if new objects of that type are expected

6. Record the exceptions, with their reason. Objects that break the rule on purpose — ported names from a base platform, legacy entry points whose names are part of a public surface. Say why renaming would cost more than the warning. An unexplained exception gets "fixed" by the next person.

7. Write .pythia/conventions.md. For every rule, state the cost of breaking it, not just the rule. "Parameter prefixes must be b_/a_" is ignorable; "the calling layer binds by prefix, so a wrong one silently unbinds the field" is not. Rules with named consequences get followed.

The LEAD's rules, machine-checked: the lint block

Rules a regex over names cannot hold, but a linter can, go in conventions.json next to naming — every pythia lint and apply preview then checks them, and autopilot will not land an error:

"lint": {
  "rules": {"varchar2-byte-semantics": "error", "dbms-output": "off"},
  "require_comments": "error",
  "required_columns": ["CREATED_BY", "CREATED_AT"],
  "param_prefix": "^P_",
  "forbid": [{"id": "no-sysdate", "pattern": "\\bSYSDATE\\b",
              "message": "use SYSTIMESTAMP", "severity": "warning"}]
}

Severities: off, info, warning, error. pythia lint --json lists every built-in rule id. Measure a new rule the same way as a naming pattern: lint a handful of existing objects (pythia src into a file) — a rule that fires on the whole codebase is a rule for new code only, and says so.

Adopting from an older base the team already runs

Point the connection at that schema and run steps 1 and 2 there — a base system with thousands of objects is the most reliable statement of a house style that exists, far better than anyone's recollection of it. Then switch the connection to the new project and run --check: coverage tells you how much of the base style the new schema has actually inherited.

Red Flags — STOP if you catch yourself thinking

Thought	Reality
"I'll write the patterns from the document alone"	Documents describe intent; schemas record what happened. Scan first.
"80% coverage is good enough"	Every miss warns on every apply. Fix the pattern or record the exception.
"I'll read all the object names to work it out"	--scan does that without spending your context.
"The schema disagrees, so the document is wrong"	It may be a new-code-only rule. Ask.
"A rule per line is enough"	A rule without its cost is a rule people skip.

When NOT to use this skill

• Writing one object in an existing style → pythia-write, which reads these files and uses similar for the details.
• Capturing a workflow with steps and gates → pythia-skill-author. Naming and style belong here; procedures belong in a skill.