Best practices

How NSTACK writes a methodology that survives contact with production.

A good methodology is not a long prompt. It is a small contract that an agent and a reviewer can both hold in their head — and then check, together, when the run is done.

Start from a single scenario

Don't try to design a generic methodology up front. Pick the most painful, most repeatable scenario your team handles right now and design for that. The library has space for variants — start narrow.

When you do, write the use-when and not-when blocks first. If you can't say in one sentence when this methodology applies, you don't have a methodology yet — you have a feeling.

Make the I/O contract a real one

An I/O contract is what lets the workbench bind your methodology to an NSTACK agent. Treat it like a function signature: what does the agent need from the world, and what does the world get back?

io:
  inputs:
    repo: { kind: git, required: true }
    target_branch: string
  outputs:
    pr_url: { kind: url }
    rationale: { kind: artifact, mime: text/markdown }

Pin the recipes you actually use

List every recipe your methodology invokes in its manifest. The validator will catch mistypes early, and reviewers will see at a glance what surface area this methodology touches.

Write one worked example before you publish

Worked examples are the single highest-leverage piece of methodology documentation. They turn an abstract spec into something a reviewer can sanity-check without running the agent.

If a teammate can't tell whether your methodology applies to their problem in 60 seconds, the methodology is not yet a methodology.

Promote on green, demote on drift

When the quality gate is green and the rationale trail looks clean, version-pin and bind to the agent. The drift watcher will tell you when reality moves away from the spec — that's your signal to revise, not to suppress the alert.