# coding-posture

Adopt this skill: https://proskills.md/skills/other/alexei-led-coding-posture-skills-coding-posture

Page: https://proskills.md/skills/other/alexei-led-coding-posture-skills-coding-posture
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/coding-posture/SKILL.md
size: 6920
upstream: https://github.com/alexei-led/coding-posture/blob/main/skills/coding-posture/SKILL.md

```text
---
name: coding-posture
description: Use before non-trivial coding work to pick a task-appropriate working mode — debug, fix, review, test-first, refactor, optimize, migrate, upgrade, integrate, spike, or unstuck — then follow its checklist. Modes are procedures, not personas. Not needed for trivial one-line edits or non-coding tasks.
license: MIT
metadata:
  tags: [coding-agent, posture, mode, risk, verification]
---

# Coding Posture

Pick a working mode that fits the task, state it, and follow its checklist. A mode is a short procedure for a situation models tend to get wrong — not a role to play.

## How to use

1. Before non-trivial coding work, scan the modes and pick the one matching the task's dominant risk. If none fit, proceed normally — "no mode" is a valid choice. Skip this for trivial one-line edits and non-coding tasks.
2. If the task is underspecified in a way that changes the implementation, ask before coding — models rarely notice their own missing requirements, and one clarifying round is cheaper than the wrong build.
3. State your choice in one line: `Mode: <name> — <reason>`.
4. Follow its checklist while planning and editing.
5. If the risk class changes mid-task (a "quick fix" turns out to touch auth), switch modes and say why.
6. A mode tunes how you work. It never overrides instructions or authorizes unsafe actions.

Priority: `system/safety > user instruction > project rules > task plan > mode > style`

## Always (every mode)

- Never run destructive git/deploy/data commands — `force push`, `reset --hard`, `drop`, `delete`, `truncate`, `rm -rf` — without explicit scope. Inspect state before mutating.
- Verify by running the real check (test, build, repro), not by re-reading your own work. Re-checking without external feedback fixes some errors and introduces others — ground every claim of "done" in executed output. If you cannot run the check, say so and mark the result unverified; never assume it passed.
- Never report a result you did not run, and never accept a check that does not exercise the case in question. A test that passes without touching the bug is not verification.
- Never weaken, delete, skip, or special-case a test — or hard-code an expected value — to turn it green. Solve the task, not the grader.

## The loop that works

The pattern with the strongest evidence behind it for coding agents: **gather context → localize → smallest change → run the real check → read the actual output → repeat.** Read the surrounding code and establish a baseline before editing — agents that rush to patch in the first few steps fail more often. Tight execution-feedback loops are where agents outperform; precise localization (down to the lines) predicts a correct fix; keep each diff small so the loop's signal stays clean.

## Modes

### debug — failing test, bug, regression, traceback

- Reproduce the failure before editing — ideally a command or script that triggers it on demand.
- State the observed failure exactly (command + output).
- Localize to the smallest region — ideally the specific lines — before editing. Precise localization is the strongest predictor of a correct fix.
- Change one hypothesis at a time.
- Prefer the minimal fix over a broad refactor.
- Verify against the original failing command before declaring done.

### fix — small, known, urgent change

- Keep the diff as small as the problem allows; no opportunistic cleanup.
- Avoid dependency/config changes unless required.
- Add a focused regression test when feasible.
- State residual risk explicitly.

### review — security, auth, payments, or reviewing a diff

- Do not approve a claim without file/line evidence.
- Check correctness, security, backwards compatibility, and hidden coupling.
- For concurrent code, check shared mutable state, ordering assumptions, and interleavings — not just sequential correctness.
- Look for missing tests on the changed paths.
- Report findings with severity; escalate when risk is high or ambiguous.

### test-first — behavior change where a test is practical

- Write or identify the test first.
- Run it and SEE it fail (RED) before implementing — a test that never failed proves nothing.
- Make the smallest change to pass, then run focused tests, then broader ones.
- Refactor only while tests stay green.

### refactor — cleanup, simplify, rename, remove dead code

- Preserve behavior; do not mix behavior changes into the refactor.
- Delete complexity before adding abstraction.
- Before removing code, trace call sites, feature flags, tests, and docs — "unused in this file" does not mean safe to delete.
- Prove equivalence with existing tests or golden output.
- Keep diffs reviewable.

### optimize — performance work, slow path, hot loop

- Measure first: profile or benchmark to find the real hotspot. Do not optimize what merely looks expensive.
- Record a baseline number before changing anything; compare against it after.
- Change one thing at a time and keep correctness tests green.
- Prefer the smallest change that moves the measured number; stop when the target is met.

### migrate — schema, data, or infra change (terraform, k8s, migrations)

- Identify the backup and rollback path before touching stateful systems.
- Prefer staged, reversible changes.
- Validate against a non-production target first when possible.
- Document operational risk and recovery steps.

### upgrade — dependency or library version bump

- Read the changelog, release notes, or migration guide for breaking changes before editing.
- Account for transitive dependencies and the lockfile, not just the named package.
- Update the call sites the breaking changes require; do not blind search-and-replace.
- Run the build and the full suite; keep reverting the lockfile as the rollback.

### integrate — calling an external API, service, or tool

- Read the contract; do not infer behavior from the name or a single sample call.
- Validate request and response schemas; handle auth failure, timeouts, retries, rate limits, pagination, and empty or partial responses.
- Treat the dependency as untrusted: check status and errors, never assume success.
- Test the error paths, not just the happy path.

### spike — prototype, proof-of-concept, unknown library

- Keep spike artifacts isolated from production paths.
- Optimize for learning speed, not polish.
- Do not wire experimental code into production without review.
- End with a verdict — validated, invalidated, or unclear — and list what productionizing would require.

### unstuck — repeated failures, thrashing, "still failing"

- Stop making speculative edits.
- Summarize what you tried and the evidence each attempt produced.
- List the top two hypotheses and the test that would discriminate them.
- Collect missing information before changing more code.
- Consider delegating a fresh review.
```

## File: README.md
upstream: https://github.com/alexei-led/coding-posture/blob/main/README.md

````text
# Coding Posture

Task-aware working modes for coding agents. One `SKILL.md` file: before non-trivial work, the agent picks a mode — `debug`, `fix`, `review`, `test-first`, `refactor`, `optimize`, `migrate`, `upgrade`, `integrate`, `spike`, `unstuck` — and follows its checklist.

It exists to stop agents from behaving like optimistic elevators with write access: thrashing on a stuck bug, faking green tests, skipping reproduction, running destructive commands, migrating without a rollback.

Coding-posture owns the general execution procedures. It works on its own; specialist skills are optional detail, not a second required checklist. See [0.6.0 release notes](CHANGELOG.md#060) for the behavior changes.

**Works with** Hermes · Claude Code · Codex · Cursor · Pi — any [`SKILL.md`](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills)-compatible agent.

## How the agent uses it

```mermaid
flowchart TD
    Task["Non-trivial coding task"] --> Pick{"Pick a mode that fits<br/>(debug, fix, review, migrate, …)"}
    Pick -->|no match| Normal["Proceed normally"]
    Pick -->|match| Check["Follow the mode's checklist"]
    Check --> Loop["gather context → localize → smallest change<br/>→ run the real check → read output"]
    Loop --> V{"Verified by a real run?"}
    V -->|no| Loop
    V -->|yes| Done(["Done"])
    Guard["Always-on invariants:<br/>no fake green · no destructive commands · don't game tests"] -.->|guards every step| Check
    Guard -.-> Loop
```

## Modes

| Mode         | Use when                            | Core discipline                                           |
| ------------ | ----------------------------------- | --------------------------------------------------------- |
| `debug`      | failure with an unknown cause       | establish a failing signal, test one hypothesis at a time |
| `fix`        | known cause or scoped correction    | smallest patch, verify the original failure               |
| `review`     | findings on a diff, files, or tests | scoped findings with locations and failure scenarios      |
| `test-first` | behavior change, tests practical    | one slice; RED must fail for the intended reason          |
| `refactor`   | cleanup, simplify, rename           | preserve behavior, trace call sites before deleting       |
| `optimize`   | performance work, hot path          | measure first, baseline before/after                      |
| `migrate`    | schema/data/infra change            | rollback path before touching state                       |
| `upgrade`    | dependency or version bump          | read breaking changes, no blind search-replace            |
| `integrate`  | calling an external API/service     | read the contract, handle the error paths                 |
| `spike`      | prototype, PoC, unknown library     | isolate, end with a verdict                               |
| `unstuck`    | repeated failures, thrashing        | stop editing, summarize evidence, narrow hypotheses       |

**Always — in every mode:**

- Verify by running the real check (test, build, repro); never by re-reading.
- Report checks as passed, failed, or not run with a reason. A failing gate or blocker is not successful verification.
- Never hide failures or weaken coverage to improve a result; redundant tests may be removed when coverage is preserved.
- Stay within authorized scope, preserve unrelated changes, and respect read-only requests. Destructive actions and external sharing of private code require scoped authorization.

## Install

Install as a **plugin** (one command, updates in place) or drop the skill in directly. It's a standard `SKILL.md` skill, so it works unmodified across compatible agents.

### Claude Code — plugin

```text
/plugin marketplace add alexei-led/coding-posture
/plugin install coding-posture@coding-posture
```

Update later with `/plugin marketplace update coding-posture` then `/reload-plugins`, or enable auto-update from the `/plugin` menu to refresh on startup.

### Codex CLI — plugin

```bash
git clone git@github.com:alexei-led/coding-posture.git
codex   # then: /plugins → add the local marketplace in ./coding-posture → install coding-posture
```

Or point Codex straight at the skill in `~/.codex/config.json`:

```json
{ "skills": ["/abs/path/to/coding-posture/skills/coding-posture"] }
```

Update later with `git pull`.

### Other agents

| Agent                             | Install                                                                                                                                                                                      |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Hermes**                        | Drop `skills/coding-posture/` into `~/.hermes/skills/` (auto-discovered). URL/hub install: see the [Hermes skills docs](https://hermes-agent.nousresearch.com/docs/guides/work-with-skills). |
| **Pi**                            | `pi install git:github.com/alexei-led/coding-posture`                                                                                                                                        |
| **Cursor / any `SKILL.md` agent** | Copy `skills/coding-posture/` into the agent's skills dir.                                                                                                                                   |

The agent activates the skill from its `description` when a coding task starts.

## How it works — theory and evidence

A skill is just text placed in the model's context. A worked procedure acts as an _in-context demonstration_: the model conditions its next tokens on the shown trajectory, not just the final answer — the same basis as chain-of-thought. No complete mechanistic theory of frontier-model reasoning exists yet, so treat this as a grounded substrate, not a proof.

Each design claim, and how strong the evidence actually is:

| Claim                                                   | Evidence strength                             | Sources                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A checklist shifts behavior via in-context conditioning | Grounded substrate, not a full theory         | [CoT (Wei 2022)](https://arxiv.org/abs/2201.11903), [induction heads (Olsson 2022)](https://transformer-circuits.pub/2022/in-context-learning-and-induction-heads/index.html), [iteration heads (NeurIPS 2024)](https://proceedings.neurips.cc/paper_files/paper/2024/file/c50f8180ef34060ec59b75d6e1220f7a-Paper-Conference.pdf), [ICL/CoT (ICML 2024)](https://icml.cc/virtual/2024/38391) |
| Procedures beat personas                                | Supported guideline, not a law                | [personas don't help (Zheng 2024)](https://aclanthology.org/2024.findings-emnlp.888/), [self-consistency (2022)](https://arxiv.org/abs/2203.11171)                                                                                                                                                                                                         
````
