nWave Cookbook

The three rules

1. Scan before you change. Ask for a report first, then decide.
2. Get a second opinion. A reviewer agent checks the report or the change. It does not edit.
3. Change in one batch, test once. Apply the planned edits together, run the tests at the end, then commit.

Think of it like a building inspector. The person who did the work should not be the only one who signs off on it.

1. Architecture Mapping

Why this category first: nwave_ai/platform/ has about 30 modules and more than 8,000 lines. That makes it hard to see where one job ends and the next begins. nwave_ai/outcomes/ already has a clean layout (domain, application, ports, adapters). Use it as the model.

Run these in order. Each one feeds the next.

Scan nwave_ai/platform/ — about 30 modules, more than 8,000 lines.
Identify: (1) which files share the same bounded context, (2) which represent
infrastructure concerns leaking into domain logic, (3) which have the highest
coupling (import fan-in/fan-out).
Output a module-responsibility table and highlight the top 3 high-coupling smells.
Then compare to nwave_ai/outcomes/ — which uses clean hexagonal structure
(domain/application/ports/adapters) — and explain the gap between them.

@nw-ddd-architect Apply bounded-context analysis to nwave_ai/platform/config.py
(about 1,200 lines). Identify: (1) distinct sub-domains mixed in this file,
(2) any aggregate roots and their invariants, (3) where the ubiquitous language
breaks down (mixed metaphors in naming).
Propose context boundaries — not refactors yet, just where the seams are.
Reference: nwave_ai/outcomes/domain/ as the target pattern.

/nw-design Using the platform/ boundary map above, propose splitting
nwave_ai/platform/ into at most 3 focused sub-packages. For each:
  1. Name the SSOT concern it owns
  2. List which current files move there
  3. State the invariant it enforces
  4. Name what currently imports it (blast radius)

Then invoke @nw-solution-architect-reviewer to challenge the split
before any changes are made.

/nw-stress-analysis Focus on nwave_ai/update/ — specifically release_discovery.py
and package_activity.py. These modules reach external systems. Identify:
  1. Every external/nondeterministic dependency
  2. What degrades vs. fails hard when each is unavailable
  3. Which failure paths propagate to the user CLI as visible errors

Output: dependency | failure mode | propagation path |
        current mitigation | recommended guard

/nw-hotspot Analyze the nwave_ai/ directory. Find the top 10 files by change
frequency over the full git history. For each: commit count, current line count,
cyclomatic complexity estimate. Flag any file where churn × complexity exceeds
a defensible threshold (use your judgment, explain the threshold).
Confirm: is cli.py in the top tier? Explain why it keeps changing.

2. Code Refactoring

The pattern: Scan → Review → Apply.

Never ask for the scan and the change in the same recipe. The separate review catches false alarms and misses that the first scan made.

Refactoring levels (RPP): /nw-refactor works through six levels, from easiest to deepest:

@nw-software-crafter Analyze nwave_ai/platform/config.py for RPP L1–L2
violations. Analyze only — report violations without applying any edits.
Report each violation as:
  file:line | level | type | one-line description

L1 (Readability): misleading names, unexplained abbreviations,
  inconsistent casing, magic numbers, dead code
L2 (Complexity): methods too long to read in one screen,
  deeply nested conditionals, complex boolean expressions

Findings list only, sorted by severity.

/nw-review Independently assess the L1–L2 findings from the config.py scan.
For each finding: CONFIRM or REJECT with one-line reason.
Additionally: scan config.py yourself for any L1–L2 violations the initial
scan missed. Output two lists:
  1. Confirmed findings in priority order
  2. New findings not in the original scan

@nw-software-crafter Apply /nw-refactor L1 to nwave_ai/platform/config.py
using the confirmed findings list only. Rules:
  1. Apply all L1 changes as one batch in a single editing session
  2. Run the test suite once, after all edits. If it is red, fix the
     production code. Do NOT modify tests to make them pass
  3. When green, commit once:
     refactor(config): apply RPP L1 readability batch
  4. Do NOT apply any L2 changes in this pass

When L1 is complete: produce an ASCII before/after diagram of the top 5
most-improved names. Then propose the next highest-value refactoring target
(file + RPP level + one-line reason why that file next).

3. Documentation Audit

Why it matters: docs/guides/ has 40+ entries. Docs go wrong in a common way called "collapse." A tutorial starts explaining theory. A how-to starts teaching concepts. Reference pages get mixed into guides. Each type should do one job.

The four DIVIO types:

@nw-documentarist Audit docs/guides/ using DIVIO/Diataxis classification.
For each document or directory:
  1. Classify: tutorial | how-to | reference | explanation
  2. State whether the content matches that type (yes / partial / no)
  3. Flag any collapse: mixed types in one doc

Output as a table:
  filename | classified-as | content-match | collapse? | top-fix-needed
Sort by severity (worst collapse first).

/nw-document Using the documentarist audit, pick the 2 documents with the
worst collapse score. For each:
  1. Rewrite the opening section to match its classified type
  2. Extract any mixed-type content into a separate correctly-typed stub
     (don't write the stub — just show its proposed title and type)
Show before/after for each rewrite.
Invoke @nw-documentarist-reviewer to confirm the rewrite resolved the
collapse without dropping essential content.

@nw-documentarist Review README.md and CONTRIBUTING.md as a first-time nWave
user who has never seen the tool. Assess:
  1. Time-to-first-working-command: how many steps before anything runs?
  2. Concept model: is the mental model explained before the commands?
  3. Error coverage: are common failure modes documented?
  4. Prerequisite clarity: are version requirements explicit?

Rate each criterion 1–5 with one sentence of evidence. End with the single
highest-ROI fix for each file.

4. Test Quality

The order matters: Clean up first, then look for gaps.

If you run mutation testing (which breaks code on purpose to see if tests notice) on a messy test suite, the results are misleading. Redundant tests cover the same code, so gaps look smaller than they are.

/nw-optimize-tests Scan the nwave_ai test suite and identify:
  1. Tests that assert Python language guarantees rather than nWave behavior
  2. Parametrize inflation: test sets where multiple params exercise the
     same code path (same branch, same logic)
  3. Exact or near-duplicate test functions

For each category: list file:test_name. Estimate total tests-to-delete
and coverage impact (expected: zero reduction in meaningful coverage).
Do NOT delete anything — produce the deletion proposal only.

@nw-test-optimizer-reviewer Independently review the test deletion proposal.
For each proposed deletion:
  1. Confirm or refute the coverage-impact estimate (run coverage if needed)
  2. APPROVE or VETO — veto if deleting removes observable-behavior coverage
  3. For vetoes: state what behavior the test pins that nothing else covers

Output: approved deletions list / vetoed list with veto reason.
Only approved deletions proceed to execution.

/nw-mutation-test Run an explicit mutation probe on:
  - nwave_ai/cli.py             (hottest by change frequency)
  - nwave_ai/platform/config.py  (largest file in platform/: about 1,200 lines)

For each surviving mutant:
  file:line | mutation type | behavior the survivor exposes |
  the test that would kill it

Sort by behavioral risk (highest first). Cap at top 10 survivors per file.

5. Feature Delivery

The rule: Check that the problem is real before you design anything.

A solution to a problem nobody has wastes the whole delivery. Ten minutes of discovery is cheaper than building the wrong thing.

The flow: discover → diverge → deliver.

/nw-discover The team reports that: [paste the specific pain point here].

Before any design or code:
  1. List every assumption embedded in this problem statement
  2. For each assumption: what evidence validates it? what invalidates it?
  3. What user or system signal confirms the problem is real and frequent?
  4. What would make this problem not worth solving?

Output: validated problem statement WITH evidence
     OR "not yet validated — still need: [specific evidence]"

/nw-diverge Given the validated problem: [paste validated statement here].

Generate exactly 3 design directions. Each must include:
  1. The JTBD (job-to-be-done) it solves
  2. The key trade-off (what this direction gives up)
  3. The minimum testable version — the skateboard: something a person
     can actually use right now, not a component of the final thing
  4. The signal that would prove this direction is wrong

Invoke @nw-diverger-reviewer to verify the 3 options are structurally
diverse and not 3 variations of the same approach.

/nw-deliver [one-sentence Request — be specific, not "add feature X"]

Route: Spine waves
Deliverable type: [code | plugin | skill | documentation]
Exit criteria: [specific observable behavior — not "it works" but e.g.
  "nwave-ai doctor shows all checks green" or
  "the CLI outputs X when given input Y with flag Z"]
Acceptance oracle: what nw-user-examiner will independently verify —
  user-visible behavior only, no internal implementation details

Related

• How-to guides — task-oriented procedures for nwdes delivery, install and upgrade.
• Skill reference — every /nw-* skill and its inputs.
• Refactoring tutorial — a guided walk through the refactoring levels.
• Mikado method — the experimental planner for large refactors, used in the refactoring recipes.

Glossary

• Recipe — one copy-paste instruction, with its agent or skill and what it produces.
• Agent — a specialist helper, written as @name. It does the work.
• Reviewer — an agent whose job is to check someone else's work. It does not edit.
• Skill — a reusable procedure, written as /name.
• Batch — applying all planned edits together, then testing once.
• Mutation testing — deliberately breaking code to see whether the tests catch it.
• Collapse — when one document mixes several kinds of writing.
• Seam — a place where code can be split without breaking things.
• Blast radius — how many other files would be affected if this one changed.

Where this came from

Built from the nWave skill and agent definitions in nWave/skills/ and nWave/agents/, and checked against this repository's file sizes and commit history. The refactoring recipes follow nWave/skills/nw-refactor/SKILL.md.