behavior-mapping

Files (1)

• SKILL.md

SKILL.md (first lines)

# Behavior mapping

The rule behind this skill is simple: **you cannot safely change behavior you
have not first written down.** On `brownfield-unmapped` familiarity the routing
policy makes this a routing guardrail floor - behavior mapping runs before any new
scenario, before any change. On an atomic or small change with trivial or
contained risk and no domain label it is advice (`RP-ADV-002`): pin what the code does now where
the change touches it with a test. This skill is how you do it well.

## What behavior mapping produces

A set of Given/When/Then scenarios that describe what the code **does
now** - not what it should do, not what the ticket wants, what it *does today*.
These go into `acceptance-criteria.md` marked as baseline scenarios. They become:

- the regression baseline - the thing the Verifier runs to prove you did not
  break what was working;
- the starting point the new scenarios are written against;
- the first time this corner of the system has been described in the shared
  vocabulary every role reads.

## The procedure

1. **Bound the surface.** You are not behavior mapping the whole system - only the
   behavior the upcoming change will touch, plus its immediate risk.
   Use the manifest's `labels:` and the plan's intended change site to draw
   the boundary. Behavior mapping too wide wastes the time the delivery
   approach allowed; too narrow misses the regression you are about to cause.
2. **Find the interfaces.** Identify the inputs and outputs of the bounded surface -
   the function signatures, the endpoints, the events, the stored state. These
   are where your `When` and `Then` will attach.
   A new user-facing surface usually wants a `ui-contract.md`, from
   `/compass:design`.
3. **Read behavior, not intent.** Trace what the code actually does for each
   input class. Resist writing what you think it *should* do - that is the new
   spec's job, and conflating them is the central behavior mapping mistake.
4. **Characterize with tests where the code is opaque.** When you cannot read
   the behavior confidently, write a *characterization test*: assert whatever
   the code returns now, even if it looks wrong, and let the green tell
   you the truth. A characterization test that documents a bug is still
   correct behavior mapping - it captures reality.
5. **Write the baseline scenarios.** One behavior per scenario, same quality
   bar as any BDD scenario (see `bdd-specification`). Name them as the current
   outcome. Mark them baseline.
6. **Flag the surprises.** Behavior mapping almost always uncovers behavior nobody
   knew about - undocumented edge cases, latent bugs, dead branches. Record each
   in `requirements-review.md`: is it behavior other code depends on and
   must preserve, or a bug to
   fix as part of this change? That decision is made deliberately, not by
   accident of what the new code happens to do.

## Behavior-mapped vs. desired - keep them separate

The most important discipline here. `acceptance-criteria.md` will end up holding two
kinds of scenario:

- **Baseline** - what the code does now. The regression baseline.
- **Target** - what the change will make it do. The new acceptance criteria.

Keep them labeled and distinct. When the change ships, some baseline scenarios
are *intentionally* superseded by target scenarios - that is a recorded
decision, not a silent overwrite. The baseline you are *not* changing must still
pass at the verify stage; that is the proof you preserved what you meant to.

## When the behavior is genuinely a mess

Sometimes the current behavior is inconsistent - the same input class does
different things depending on undocumented state. Map it honestly anyway:
write the scenarios that capture the inconsistency. The mess, written down, is
something you can decide about. The mess, undescribed, is something that will
surprise you at the verify stage or in production.

## Anti-patterns

- **Behavior mapping the ideal.** Writing scenarios for what the code should do and
  calling it behavior mapping. Now you have no regression baseline and a spec that lies
  about the present.
- **Mapping too much.** Behavior mapping far beyond the change's risk. The
  delivery approach did not allow for it and it delays the actual work.
- **Skipping it because "I understand this code."** Understanding it is not the
  bar - *it being written down* is the bar. The floor is about the artifact, not
  your confidence.
- **Silent supersession.** Letting a target scenario quietly replace a baseline
  one with no recorded decision about whether that behavior change was
  intended.

From ayeo-io/compass, Apache-2.0.

More from ayeo-io/compass