Behavioral Spec Writing

Behavioral Spec Writing

Layer 3 transforms Layer 2 synthesis (module map, feature inventory, architecture doc, API surface, behavioral summaries) into specifications detailed enough that a developer can reimplement the target WITHOUT seeing the original code. This skill carries all methodology for deep-dive-analyzer, contract-extractor, behavior-documenter, and user-journey-analyzer.

Layer 3 Pipeline Overview

digraph layer3_pipeline {
    rankdir=TB;
    compound=true;

    "Layer 2 synthesis complete" [shape=doublecircle];
    "Layer 3 complete — proceed to Gate 1" [shape=doublecircle];

    subgraph cluster_phase1 {
        label="Phase 1: Per-Module Deep Dives (parallel across modules)";
        style=dashed;

        "deep-dive-analyzer: Module A" [shape=box];
        "deep-dive-analyzer: Module B" [shape=box];
        "deep-dive-analyzer: Module N" [shape=box];
    }

    subgraph cluster_phase2 {
        label="Phase 2: Cross-Cutting Documentation (parallel)";
        style=dashed;

        "contract-extractor: external + integration contracts" [shape=box];
        "behavior-documenter: behavioral domain synthesis" [shape=box];
        "user-journey-analyzer: end-to-end journeys" [shape=box];
    }

    "Layer 2 synthesis complete" -> "deep-dive-analyzer: Module A";
    "Layer 2 synthesis complete" -> "deep-dive-analyzer: Module B";
    "Layer 2 synthesis complete" -> "deep-dive-analyzer: Module N";

    "deep-dive-analyzer: Module A" -> "contract-extractor: external + integration contracts" [lhead=cluster_phase2];
    "deep-dive-analyzer: Module B" -> "behavior-documenter: behavioral domain synthesis" [lhead=cluster_phase2];
    "deep-dive-analyzer: Module N" -> "user-journey-analyzer: end-to-end journeys" [lhead=cluster_phase2];

    "contract-extractor: external + integration contracts" -> "Layer 3 complete — proceed to Gate 1";
    "behavior-documenter: behavioral domain synthesis" -> "Layer 3 complete — proceed to Gate 1";
    "user-journey-analyzer: end-to-end journeys" -> "Layer 3 complete — proceed to Gate 1";
}

Phase 1 runs deep-dive-analyzer in parallel across every module from the module map. Each instance produces a per-module behavioral specification.

Phase 2 runs three agents in parallel. They consume Phase 1 output plus Layer 2 synthesis to produce contracts, behavioral documentation, and user journeys.

Input Sources

Required (from Layer 2 synthesis)

Consulted (from Layer 1 raw intelligence)

Claims supported by multiple independent intelligence sources earn confirmed confidence.

Per-Module Behavioral Specification (deep-dive-analyzer)

This is the primary Layer 3 deliverable. Each module in the module map gets a complete behavioral specification written to workspace/raw/specs/modules/{module-name}.md.

Black Box Methodology (CRITICAL)

You read source code to understand behavior. You NEVER reference source code in specs.

Even though you analyze code, your output must read as if you only observed the system externally. The test: "Can someone implement this from my spec alone, never having seen the source?"

What You NEVER Include (Implementation Details)

External System Exception (NON-NEGOTIABLE)

When the target application depends on external systems it does not own — shared databases, third-party APIs, CLI tools it shells out to, file formats imposed by other systems, hardware interfaces — the details of those systems are behavioral constraints, not implementation details.

The test: Can the reimplementor redesign this interface? If NO (it's external/shared/imposed), treat its details as external contracts and INCLUDE them. If YES (the app owns it), treat them as implementation details and EXCLUDE them.

Examples of external constraints that MUST be preserved:

• External database schemas: table names, column names, cardinalities, naming collisions, derivation relationships, join-correctness constraints — because the reimplementation must query the same schema
• Third-party API contracts: endpoint paths, request/response field names, pagination schemes, rate limits, auth flows — because the reimplementation must call the same API
• External CLI tools: command names, flag names, output formats — because the reimplementation must invoke the same tools
• Imposed file formats: field names, encoding rules, version headers — because the reimplementation must read/write the same files
• Hardware/protocol constraints: register layouts, packet formats, timing requirements — because the reimplementation must talk to the same hardware

Document external system contracts in dedicated files under workspace/raw/specs/contracts/ (see Contract Extraction section). These contracts flow through to the implementer unchanged.

What You ALWAYS Include (Behavioral Interfaces)

The rule: If a user or external system needs to know it, INCLUDE it. If only the code needs to know it, EXCLUDE it.

Transformation Examples

WRONG:

Entry point: main() at src/cli.ts:45
Calls parseArgs() which returns Config object
Variable requestId = generateUUID()

RIGHT:

Entry point: Command-line invocation

Behavior:
1. Parse arguments into configuration
2. Generate session identifier (UUID v4 format)
3. Initialize modules based on config

Session ID: UUID v4, generated once at startup, immutable

SPEC ID Format

Every behavioral claim gets a unique ID: SPEC-{DOMAIN}-{NNN}

Where {DOMAIN} is a short uppercase token for the behavioral domain (use tokens that describe exposed behavior, NOT internal module names) and {NNN} is a zero-padded sequential number starting at 001.

Pick tokens that describe the target's exposed behavior. The set below is a starting vocabulary; delete what doesn't apply and add tokens that do.

For any behavior the starting set doesn't cover, create a descriptive token — for example: CACHE, MIGRATE, HEALTH, LOADER, WATCH, AUDIO, PARSER, SYNC, PLUGIN, SESSION, TOOL. Tokens describe the target's actual surface; a speech-to-text app probably needs AUDIO and UI; a web service probably needs NET and DATA; a code-loading tool probably needs PARSER and CONFIG. Don't carry tokens you don't need.

If a module's behavior spans multiple domains, use multiple tokens (one per behavioral block). IDs MUST be unique across the entire spec file. Examples: SPEC-CLI-001, SPEC-CONFIG-042, SPEC-API-003, SPEC-AUDIO-007.

Requirement Levels (IETF RFC 2119)

Every behavioral claim in the spec MUST be annotated with a requirement level:

• MUST -- Absolute requirement. The implementation is non-compliant if this is not satisfied. The implementer MUST exhibit this behavior.
• SHOULD -- Recommended. There may be valid reasons to deviate, but the implications must be understood and divergence requires documented rationale.
• MAY -- Optional. The implementation can choose to include or omit this behavior.

Apply requirement levels to every entry point behavior, every decision tree outcome, every error condition, and every state transition. If a claim lacks a requirement level, it is ambiguous and must be clarified.

Spec Structure Template

Each per-module spec covers the following sections. All sections are required; write "Not applicable" or "Stateless" where a section genuinely does not apply, but never omit sections.

1. Overview

2-3 paragraphs: what the module does from a user/system perspective, why it exists, key responsibilities.

2. Behavioral Interfaces

Exposed Capabilities

For each capability this module makes available:

- **Capability:** [behavioral name -- what it does, not what it's called internally]
- **Trigger:** [what causes this capability to activate]
- **Preconditions:** [what MUST be true before invocation]
- **Postconditions:** [what is guaranteed after completion]
- **Error conditions:** [what errors can occur and when]
- **Requirement Level:** MUST | SHOULD | MAY

Prerequisites

For each capability or data this module needs to function:

- **What is needed:** [capability or data description]
- **When:** [at what point this prerequisite is consumed]
- **Failure behavior:** [what happens if the prerequisite is unavailable]

CRITICAL: Do NOT name which module provides the prerequisite. Describe WHAT is needed, not WHERE it comes from. A "From module" field would be structural contamination. The implementer decides its own module boundaries.

3. Entry Points

For each way to invoke this module:

#### SPEC-{DOMAIN}-{NNN}: [Descriptive Name]
**Requirement Level:** MUST | SHOULD | MAY

### Trigger
[What causes this to be invoked -- user action, event, timer, etc.]

### Input
- Parameter 1: [type] - [what it represents]
- Parameter 2: [type] - [what it represents]
- Required state: [what must be true before invocation]

### Behavior
1. **Validation**
   - Check: [what condition] -> if invalid: [error message]
   - Check: [what condition] -> if invalid: [error message]

2. **Processing**
   - [Step-by-step behavioral description]
   - Decision: if [condition in behavioral terms]
     - Then: [behavior]
     - Else: [behavior]

3. **Completion**
   - Output: [what is returned/emitted]
   - State change: [what persists]
   - Side effects: [files written, network calls, etc.]

4. Decision Trees

For every significant decision, document in behavioral terms:

#### SPEC-{DOMAIN}-{NNN}: [What is being decided]
**Requirement Level:** MUST | SHOULD | MAY

### Conditions (evaluated in order)
1. If [behavioral condition]: -> [behavioral outcome]
2. Else if [behavioral condition]: -> [behavioral outcome]
3. Default: -> [behavioral outcome]

### Outcomes
- **Outcome 1**: [detailed behavioral description]
- **Outcome 2**: [detailed behavioral description]

Describe conditions by what they MEAN, not how they are coded:

• WRONG: if (x.length > 0 && x[0] === '-')
• RIGHT: "if input starts with a dash (indicating a flag)"

Conditional Error Handling Pattern

Pay special attention to behaviors that differ based on HOW a feature was triggered. A common pattern:

• Auto-detected configuration -- lenient error handling (log warning, continue)
• User-specified configuration -- strict error handling (error, abort)

When the same feature has different error handling based on whether it was explicitly requested vs. automatically discovered, document BOTH paths explicitly:

#### SPEC-{DOMAIN}-{NNN}: Configuration Error Handling
**Requirement Level:** MUST

### Conditions
1. If configuration was auto-detected AND loading fails: -> Log warning, continue without it
2. If configuration was user-specified (via flag/option) AND loading fails: -> Report error, abort
3. If configuration loads but is invalid: -> [behavior depends on which fields are invalid]

This pattern appears frequently in config file loading, plugin/extension discovery, and feature detection with fallback.

5. State Model (State Box)

If the module maintains state, this section is MANDATORY. Every stateful module must document its states, transitions, and invariants explicitly — implementers need the state model to preserve behavior across a rewrite.

## State Model (State Box)

### State Variables
| Variable | Type | Initial Value | Description |
|----------|------|---------------|-------------|
| [name] | [type] | [initial] | [what it represents] |

### State Invariants
[What MUST always be true about the state, regardless of transitions]

### States
- **Idle**: [what this state means, invariants]
- **Processing**: [what this state means, invariants]
- **Complete**: [what this state means, invariants]

### Transitions

| From | Event | Condition | Action | To |
|------|-------|-----------|--------|-----|
| Idle | request received | valid input | begin processing | Processing |
| Processing | work complete | success | emit result | Complete |
| Processing | error occurs | - | emit error | Idle |

### State Persistence
[Where state lives (memory, disk, database), lifetime, serialization format]

### Initialization
[How the state machine starts]

### Termination
[How/when the state machine ends]

If the module is stateless, write: "Stateless -- This module maintains no state between invocations."

6. Error Handling

Error specification MUST be as detailed as normal operation. For every entry point, the error paths must have the same depth as the happy path. Incomplete error documentation is a spec gap.

For EVERY error condition:

#### SPEC-{DOMAIN}-{NNN}: [Descriptive Error Name]
**Requirement Level:** MUST | SHOULD | MAY

### Trigger
[What situation causes this error]

### Detection
[How the system knows this error occurred]

### Response
1. [First action -- e.g., "Log error details"]
2. [Second action -- e.g., "Clean up partial state"]
3. [Final action -- e.g., "Return error to caller"]

### User-Visible Message
"[Exact error text the user sees]"

### Recovery
[Can the operation be retried? Under what conditions?]

7. Edge Cases

## Edge Cases

### Empty Input
- Behavior: [what happens]
- Output: [what is returned]

### Maximum Size
- Limit: [what the limit is]
- Exceeded behavior: [what happens]

### Concurrent Access
- Behavior: [how handled]
- Guarantees: [what is guaranteed]

### Interruption
- Cleanup: [what cleanup occurs]
- Resumability: [can it resume?]

8. Configuration Effects

How configuration values alter this module's behavior. For each relevant config key:

| Config Key / Env Var | Effect on This Module | Default | Requirement Level |
|---------------------|----------------------|---------|-------------------|
| `SOME_ENV_VAR` | Enables debug output for this module | unset (disabled) | MAY |
| `configKey` | Controls retry count | 3 | SHOULD |

9. Data Formats

## Data Format: [Name]

### Input
{
  field1: string (required, 1-100 chars),
  field2: number (optional, default: 0),
  field3: array of strings (required, non-empty)
}

### Transformations
1. Validate all required fields present
2. Apply defaults to optional fields
3. Normalize field1 to lowercase

### Output
{
  field1: string (normalized),
  field2: number,
  field3: array of strings,
  computed: boolean (true if field2 > 0)
}

10. Dependency API Contracts

When the target delegates critical behavior to a third-party library, document the exact API contract used. These are behavioral contracts between the target and external systems -- equivalent to wire protocols -- NOT implementation details.

digraph dependency_contract_decision {
    rankdir=TB;

    "Target calls dependency?" [shape=diamond];
    "Is behavior delegated?" [shape=diamond];
    "Document API contract" [shape=box];
    "Skip -- internal detail" [shape=box];

    "Target calls dependency?" -> "Is behavior delegated?" [label="yes"];
    "Target calls dependency?" -> "Skip -- internal detail" [label="no"];
    "Is behavior delegated?" -> "Document API contract" [label="yes: critical behavior\ndepends on correct API usage"];
    "Is behavior delegated?" -> "Skip -- internal detail" [label="no: wrapper only"];
}

For each critical dependency contract, document:

API Surface Used:

• Function/method called and its purpose
• Required parameters and what they control
• Which options MUST be set for correct behavior (and what goes wrong without them)

Failure Modes:

• What happens if required options are omitted or wrong
• What the dependency's default behavior is (when it differs from what the target needs)
• Fallback behavior when the dependency is unavailable

Version Constraints:

• Minimum version required and why
• Breaking changes across versions that affect the target

Example:

## Dependency Contract: esbuild Transform API

### API Surface Used
- `esbuild.transform(code, options)` -- transforms TypeScript/JSX to JavaScript
- Required option: `loader` must be set explicitly ('ts', 'tsx', 'jsx') based on source file extension
- Required option: `sourcefile` OR explicit `loader` -- without either, esbuild defaults to JavaScript parsing
- The `transform()` API receives code as a string (no filename), so it cannot infer the loader automatically

### Failure Mode
- If `loader` is 'default' and no `sourcefile` is provided: TypeScript syntax (`interface`, `enum`, type annotations) causes parse errors
- Error: "Expected ';' but found 'Identifier'"

### Version Constraint
- Requires esbuild >= 0.14.0 for stable transform API

The rule: If the target's correctness depends on calling a dependency's API with specific parameters, that is a behavioral contract. Document it.

11. Uncertainty Categories

Explicitly categorize gaps using the POSIX three-category model:

## Implementation-Defined Behavior
[Areas where the implementor has freedom to choose, with any constraints.
The implementor MUST document their choice.]

## Unspecified Behavior
[Valid behaviors the spec does not prescribe -- any correct approach is acceptable.
The implementor need not document their choice.]

## Undefined Behavior
[Inputs or states the spec does not cover -- implementation may do anything.
No guarantees are made about these scenarios.]

Exhaustive Reading Requirement (CRITICAL)

You MUST read every single line of code in the module. No exceptions.

• Do NOT skim. Do NOT skip sections that "look unimportant."
• Do NOT rely solely on grep/search patterns -- READ the actual source files.
• Every routine (function, method, class, handler) must be identified.
• Every line of code must be understood in context.
• If you have not read it, you do not know what it does.

Checklist before proceeding:

• I have read every source file relevant to this module
• I have identified every routine in those files
• I have traced every code path, not just the obvious ones
• I have examined every conditional branch

If you cannot check these boxes, GO BACK and read more.

Saturation Stopping Criterion

Do not pursue exhaustive analysis past the point of diminishing returns. When successive analysis passes stop revealing new behavioral observations for a module, document current understanding and move on. P0 modules warrant more thoroughness than P2/P3 modules, but even P0 analysis should stop when saturated. The goal is "sufficient to reimplement," not "every conceivable edge case."

Depth Standard

For each behavior, you must answer:

1. What EXACTLY triggers it?
2. What EXACTLY happens in each case?
3. What EXACTLY can go wrong?
4. What EXACTLY is the output?

WRONG: "It validates the input" -- TOO VAGUE

RIGHT: "It checks: field X is non-empty string (error: 'X required'), field Y is positive integer (error: 'Y must be positive'), field Z matches pattern /^[a-z]+$/ (error: 'Z must be lowercase letters')" -- COMPLETE

Cross-Agent Reconciliation

When extraction analysis files from multiple agents exist for overlapping topics:

1. Read ALL extraction files that touch your module, not just the primary one
2. Compare claims between extraction files -- look for disagreements on algorithms, constants, field names
3. When agents disagree, go to the source -- read the actual code at the cited line numbers
4. Resolve before writing -- your spec must contain the verified truth, not a guess from one agent

If you find a contradiction you cannot resolve from the source, record it with a disputed citation:

<!-- cite: source=source-code, ref=workspace/raw/source/analysis/chunk-0024.md:105, confidence=disputed, agent=deep-dive-analyzer, contradiction=workspace/raw/source/exploration/auth-layer/findings.md:23 -->

Multi-Source Consultation

When other intelligence sources have run, consult their findings:

• workspace/public/docs/ -- official documentation claims
• workspace/public/ecosystem/ -- SDK analysis findings
• workspace/public/community/ -- tutorials, reviews, forums, issue tracker observations
• workspace/raw/runtime/ -- runtime observation data
• workspace/raw/binary/ -- binary analysis findings

Claims supported by multiple independent sources earn confirmed confidence.

Self-Assessment Checklist

Every per-module spec file MUST end with this checklist:

## Verification Checklist
- [ ] All entry points documented
- [ ] All decision trees traced (every branch, including error paths)
- [ ] All state machines documented (states, transitions, triggers)
- [ ] All error conditions listed with observable symptoms
- [ ] All edge cases identified and documented
- [ ] Auto-detected vs user-specified behavior differences documented
- [ ] Zero source code identifiers in this document
- [ ] All behavioral claims have provenance citations
- [ ] Assumed claims are a small minority; most claims have direct evidence
- [ ] No sections are empty or placeholder-only
- [ ] Cross-references to other specs are valid
- [ ] Every behavioral claim has a SPEC-{DOMAIN}-{NNN} ID
- [ ] Every behavioral claim has a requirement level (MUST/SHOULD/MAY)
- [ ] Error conditions have equal depth to normal operations
- [ ] All stateful modules have State Box documentation
- [ ] Uncertainty sections (implementation-defined/unspecified/undefined) present
- [ ] Behavioral Interfaces section (Exposed Capabilities/Prerequisites) present
- [ ] Dependency API contracts documented for all critical third-party calls
- [ ] Contamination Self-Check completed (all checks pass)

Contamination Self-Check Protocol

HARD STOP: Review your output file BEFORE writing it. Read every line and apply the reimplementor test from the spec-sanitization skill. Do NOT write the file until all checks pass.

For every identifier, name, or reference in your spec, ask: "Could the reimplementor reasonably redesign this?"

• If YES → it's an implementation detail. Rewrite it as behavioral description.
• If NO → it's an external contract. Keep it exactly.

Check each paragraph for:

1. Internal names — variable names, function signatures, class names, method names from the source (any language). These constrain the reimplementor's design choices without behavioral necessity.
2. Internal architecture — module boundaries, file organization, inheritance hierarchies described in prose. The spec structure should reflect behavioral domains, not source code structure.
3. Framework-specific patterns — state management internals, ORM patterns, framework lifecycle hooks described by internal name rather than behavior.
4. Build/deployment artifacts — source file paths, line numbers, chunk IDs, minified identifiers, bundle structure references.
5. Code structure language — "calls X then Y", "inherits from Z", "implements interface W". Describe the observable behavior instead.

External contracts to PRESERVE (not contamination):

• User-facing identifiers: CLI flags, env vars, config keys, config file paths
• Wire protocol fields: API endpoints, request/response field names, header names
• Published constants: error message text, exit codes, timeout values
• Standard names: protocol names, encoding names, algorithm names
• Dependency API calls: documented third-party interfaces the reimplementor must also call

If any implementation detail is found: rewrite the line using behavioral language, then re-check. Only write the file when the spec reads cleanly to someone who has never seen the source.

Per-Module Spec Output Template

# Module: [Descriptive Name]

## Overview
[2-3 paragraphs: what it does, why it exists, key responsibilities]

## Behavioral Interfaces

### Exposed Capabilities
[For each capability: name, trigger, preconditions, postconditions, errors, req level]

### Prerequisites
[For each need: what is needed, when, failure behavior -- NO "From module" field]

## Entry Points
[Each entry point with full behavioral spec, including SPEC-{DOMAIN}-{NNN} IDs]

## Decision Logic
[All significant decision trees with SPEC IDs]

## State Model (State Box)
[State variables, invariants, transitions if stateful, or "Stateless" if not]

## Error Handling
[All error conditions with equal depth to normal operations]

## Edge Cases
[Boundary conditions]

## Configuration Effects
[How config values alter behavior]

## Data Formats
[Input/output schemas]

## Dependency API Contracts
[Third-party library contracts]

## Implementation-Defined Behavior
[Areas where the implementor has freedom to choose]

## Unspecified Behavior
[Valid behaviors the spec does not prescribe]

## Undefined Behavior
[Inputs or states the spec does not cover]

## Verification Checklist
[Self-assessment checklist -- see above]

Contract Extraction (contract-extractor)

The contract-extractor produces two categories of output: contracts that cross the analysis/implementation boundary to the implementer, and inter-module contracts that stay in analysis for verification purposes only.

External Contracts (FLOW TO IMPLEMENTATION)

Observable interfaces between the target and the outside world. These are things a user or external system can observe without seeing source code.

CLI Contract

Document every command and subcommand, every flag, required vs optional arguments, default values, and exit codes.

## Main Command

Usage: `target [options] [command]`

### Global Flags

| Flag | Short | Type | Default | Description |
|------|-------|------|---------|-------------|
| `--help` | `-h` | boolean | false | Show help |
| `--version` | `-v` | boolean | false | Show version |

### Subcommands

#### `target init`
[Arguments, flags, exit codes]

### Exit Codes
| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General error |
| 2 | Usage error |

Output: workspace/raw/specs/contracts/cli.md

Environment Contract

Output: workspace/raw/specs/contracts/environment.md