---
name: better-coding-orient
description: "Route every new or not-yet-scoped coding task to the right process level — the entry point when work arrives that has no route yet. MUST be used when a feature request, bug report, refactor, or vague task arrives and no task size has been assessed, or when a new/unfamiliar codebase must be understood before changing it — even if the user does not say orient or plan. Assesses task size (trivial/small/medium/large), picks the skill chain, bootstraps a project constitution (CLAUDE.md/AGENTS.md) on first run, and cross-checks existing spec/plan/tasks artifacts. Routes and hands off; does not plan or code itself. If the task arrives already clearly scoped — a named one-line fix, a concrete failing test — the matching skill may run directly without this router. Trigger: /better-coding-orient"
metadata:
  version: "2.12.0"
  license: Apache-2.0
---

# Better Coding Orient

The router and steering skill — the first thing that runs when a coding task
arrives. Without it, the agent either applies heavy ceremony to a one-line fix
(overhead) or skips planning on a new subsystem (danger). This skill makes the
rigor-scaling decision explicit and bootstraps the project rules that every
later phase references.

**Primary objective:** route the task to the right process level, and ensure
the project has a constitution before any design work begins.

---

## Activation

Begin the first response after loading with exactly this line:
▸ better-coding-orient active — route, assess, steer

Emit it once, then proceed.

---

## Part 1 — Routing (every task)

### Assess task size

| Size | Example | Route to |
|------|---------|----------|
| **Trivial** | Fix a typo, rename a variable, one-line fix | Skip to `/better-coding-workflow`. State "skipping planning — trivial change." |
| **Small** | Add a field to a form, extend an API endpoint with similar logic | Quick spec sketch (inline) then `/better-coding-workflow` then `/better-coding-review` |
| **Medium** | New feature in an existing module, refactor with clear boundaries | `/better-coding-plan` then `/better-coding-workflow` then `/better-coding-review` then `/better-coding-verify` |
| **Large** | New subsystem, cross-cutting feature, architectural change | `/better-coding-plan` then `/better-coding-workflow` then `/better-coding-review` then `/better-coding-audit` then `/better-coding-verify` |

When unsure, default to one level heavier. The cost of over-planning is minutes;
the cost of under-planning is hours of rework and context rot.

**Fast path:** if the task arrives already clearly scoped and sized — a named
one-line fix, a concrete failing test, a well-defined micro-change — skip the
routing ceremony. State the size in one line and proceed directly with the
matching skill (`/better-coding-workflow`, `/better-coding-debug`).

### Scope check

If the request spans multiple independent subsystems, stop and propose
decomposition:

> "This request covers [A], [B], and [C] — three independent subsystems. I
> recommend separate specs and plans for each. Shall I start with [A]?"

Each subsystem gets its own spec, plan, and implement cycle. Do not refine
details of something that needs splitting first.

### UI check

If the task involves user-facing UI, note that `/better-coding-frontend` should
be paired with `/better-coding-workflow` during implementation.

### Security check

If the task touches `auth/`, `payments/`, `user-data/`, or security-critical
infrastructure, note that `/better-coding-audit` should run after
`/better-coding-review`.

### Routing output

State the routing decision explicitly:

```
Task:    [one-line description]
Size:    [trivial/small/medium/large]
Route:   [skill chain]
UI:      [yes/no — if yes, pair with /better-coding-frontend]
Security:[standard/high — if high, add /better-coding-audit]
```

Then invoke the first skill in the chain (or proceed directly to
`/better-coding-workflow` for trivial tasks).

---

## Part 1.5 — Codebase Exploration (unfamiliar code)

When the task lands in an unfamiliar or legacy area, explore before routing
onward — reading is cheaper than rework:

- **Read in this order** (recon before deep reading): the package manifest
  (`package.json`/`pyproject.toml`/`go.mod`/…), framework config, the main
  entry point, the top-level directory structure (2 levels), then
  `.env.example` and CI workflows for run/deploy clues. Only dive deep where
  this recon is ambiguous.
- **Explore first, write nothing.** Answer "how does X work here?" as if
  asking a colleague: read the relevant files and summarize. No code changes
  during exploration — research and implementation stay strictly separate.
- **Trust code over config.** When a config signal and the actual code
  conflict, believe the code. Flag what you cannot determine ("could not
  determine the test command") rather than inventing an answer.
- **Follow the pattern.** Find one similar existing implementation and read it
  completely; new code imitates its structure, conventions, and libraries
  rather than starting from scratch.
- **Read the project's memory.** CONTEXT.md/glossary, ADRs for the affected
  area, and the constitution — then use the project's own terminology.
- **Use git history.** `git log` / `git blame` on the affected files explains
  why the code is the way it is and who changed it last.
- **Identify the skeleton.** Entry points, layers, data models, and the
  dependency hotspots the change will touch.
- **Blast radius before change.** List the call sites and consumers the change
  affects — this feeds directly into the routing size decision.
- **Scope the exploration.** It has a goal and an end — no infinite wandering.
  If the agent supports subagents, delegate broad reading to one and keep only
  the summary in context.

---

## Part 2 — Steering / Constitution (first run only)

### When to run

Run the steering setup if:
- This is the first coding task in the project, OR
- No `CLAUDE.md`, `AGENTS.md`, or `constitution.md` exists, OR
- The user explicitly asks to set up project conventions.

Skip silently if a constitution already exists — read it and proceed. This
skill writes the stack/commands/conventions block; the `## Coding workflow`
block is owned by `/better-coding-start`. If both run, they coexist as separate
sections — do not duplicate. For a full session boot (workflow map + durable
re-invocation rule), that is `/better-coding-start`, run once before routing —
it may also invoke this Part 2 when the user asks for project info during boot.

### Steps

1. **Detect the stack** — read `package.json`, `pyproject.toml`, `Cargo.toml`,
   `go.mod`, `pom.xml`, or equivalent. Identify: language, framework, test
   runner, build/lint commands, directory structure, dependency policy.

2. **Ask for missing context** — if the manifests do not reveal the test
   command, lint command, or directory conventions, ask. One batch of
   questions, not one at a time.

3. **Write the constitution** — create or update `CLAUDE.md` (Claude Code)
   and/or `AGENTS.md` (Codex). If one already exists, **enhance it, don't
   replace it** — preserve the team's existing rules and mark what you add.
   Structure it with:

```markdown
# Project: [name]

## Tech stack
- Language: [e.g. TypeScript 5.4]
- Framework: [e.g. Next.js 15]
- Test runner: [e.g. vitest]
- Linter: [e.g. eslint]
- Build: [e.g. npm run build]

## Commands
- Test:    [e.g. npm test]
- Lint:    [e.g. npm run lint]
- Build:   [e.g. npm run build]
- Format:  [e.g. npm run format]

## Conventions
- [e.g. We use TDD: tests are written before implementation]
- [e.g. We use Conventional Commits: feat:, fix:, refactor:, test:, docs:]
- [e.g. No new dependencies without justification in the PR]

## Architecture
- [e.g. src/ contains application code, tests/ mirrors src/ structure]
- [e.g. Dependencies point inward: infrastructure -> domain, never reverse]
```

4. **Express rules as declarative statements** — prefer testable, enforceable
   rules over blanket statements. EARS syntax is a good fit:
   - Ubiquitous: "The system shall [always behavior]"
   - Event-driven: "When [event], the system shall [response]"
   - State-driven: "While [state], the system shall [behavior]"
   - Unwanted: "The system shall prevent [unwanted behavior]"

5. **Commit the constitution** to git. Treat changes as reviewable.

### Guardrails

- **Keep it lean.** Codex truncates instruction files at 32 KiB
  (`project_doc_max_bytes`). A 5,000-line CLAUDE.md degrades results. Push
  detail into skills, not the constitution.
- **Rules must be verifiable.** "Never converge across generations" is
  impossible — the model cannot see other sessions. If the agent cannot verify
  a rule, it cannot follow it.
- **Prefer specific over blanket.** "Use parameterized queries for all SQL
  with user input" beats "be secure."
- **No rules that reference inaccessible information.** If the rule depends on
  data the agent cannot access (other sessions, external systems, future
  state), it will be ignored and erodes trust in all other rules.
- **Earn-its-place test.** For each line ask: *would removing this cause the
  agent to make a mistake?* If not, cut it. Include what the agent can't infer
  from the code (non-obvious commands, project-specific conventions, gotchas);
  exclude what it can (standard language idioms, "write clean code",
  file-by-file descriptions). A bloated constitution gets half-ignored.
- **Emphasis and pruning.** Use IMPORTANT / YOU MUST sparingly on the rules
  that adherence keeps slipping on. If the agent keeps violating a rule that is
  present, the file is likely too long and the rule is lost in the noise —
  prune, don't add.

---

## Part 3 — Cross-Artifact Analysis (when artifacts exist)

### When to run

Run analysis when a spec, plan, and/or tasks file already exist (from
`/better-coding-plan`) and before implementation begins. This is the quality
gate that catches inconsistencies while they are still cheap to fix.

### Steps

1. Read all existing artifacts: `spec.md`, `plan.md`, `tasks.md` (or wherever
   `/better-coding-plan` saved them).
2. Check for:
   - **Coverage gaps** — every requirement in the spec has at least one task
   - **Orphaned tasks** — every task traces back to a requirement
   - **Placeholders** — "TBD", "TODO", "add error handling", "similar to Task N"
   - **Type/name drift** — function names and signatures match across tasks
   - **Constitution violations** — does the plan violate any MUST rule?
   - **Contradictions** — does the plan contradict the spec? Do tasks
     contradict the plan?
3. Rate findings by severity:
   - **Critical** — constitution violation, missing requirement, placeholder
   - **Important** — type drift, contradiction, coverage gap
   - **Minor** — naming inconsistency, unclear task description
4. Present the analysis report. Fix all Critical findings before proceeding to
   `/better-coding-workflow`.

### Guardrails

- This is **read-only**. Do not modify the artifacts — report findings and let
  the user (or `/better-coding-plan`) fix them.
- Constitution violations are always Critical.
- Run analysis *before* implementation so gaps are cheap to fix.

---

## Rationalization Prevention

| Excuse | Reality |
|--------|---------|
| "This looks simple, I'll just code it" | Simple tasks break too. Assess first — it takes 10 seconds. |
| "I don't need a constitution for this project" | Every project needs rules. Without them, the agent guesses at conventions. |
| "The spec and plan look fine, skip analysis" | Analysis catches drift you cannot see by reading individually. |
| "I'll figure out the scope during implementation" | Scope discovered during implementation is scope creep. Assess first. |
| "Multiple subsystems? I'll handle them together" | Combined subsystems produce combined bugs. Decompose first. |

---

## Red Flags — STOP

- About to start coding without assessing task size
- About to plan a one-line fix (overhead)
- About to skip planning on a multi-file feature (danger)
- Constitution is 5000+ lines (Codex will truncate it)
- Rules that reference information the agent cannot access
- Multiple independent subsystems being forced into one spec

---

## Terminal States

After routing, this skill invokes the next skill in the chain:

- **Trivial** → invoke `/better-coding-workflow`
- **Small** → inline spec sketch, then invoke `/better-coding-workflow`
- **Medium/Large** → invoke `/better-coding-plan`
- **If UI** → note: pair `/better-coding-workflow` with `/better-coding-frontend`
- **If security-sensitive** → note: add `/better-coding-audit` after review
- **If artifacts exist** → run analysis, then invoke `/better-coding-workflow`
- **If no constitution** → run steering setup first, then route

Do not proceed to implementation without either (a) routing to
`/better-coding-plan` for non-trivial tasks, or (b) explicitly stating
"skipping planning — trivial change" for trivial tasks.

---

## Relationship to the other skills

- `/better-coding-plan` — the planning skill this router invokes for
  medium/large tasks. It produces the spec, plan, and task list.
- `/better-coding-workflow` — the implementation skill this router invokes for
  trivial/small tasks, or that follows `/better-coding-plan`.
- `/better-coding-review` — reviews the diff that `/better-coding-workflow`
  produces.
- `/better-coding-audit` — security and whole-repo assessment, added to the
  chain for security-sensitive tasks.
- `/better-coding-debug` — invoked when something breaks during implementation.
- `/better-coding-frontend` — paired with `/better-coding-workflow` for UI tasks.
- `/better-coding-verify` — the evidence gate that closes every non-trivial
  task chain.