/behavioral-spec-writing

name: behavioral-spec-writing
description: Layer 3 deep documentation methodology. Per-module behavioral specifications, external and behavioral integration contracts, behavior documentation, end-to-end user journey analysis. Transforms Layer 2 synthesis into implementable behavioral specifications. Loaded by the analyzer agent during Layer 3.

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)

| Path | What It Contains | |------|-----------------| | `workspace/raw/synthesis/module-map.md` | Module inventory: name, description, priority, dependencies | | `workspace/raw/synthesis/features/` | Feature inventory across all sources | | `workspace/raw/synthesis/architecture/` | Architecture document: component relationships | | `workspace/raw/synthesis/api/` | API surface: all discovered interfaces | | `workspace/raw/synthesis/behavioral-summaries/` | Merged intelligence from all Layer 1 modes | | `workspace/raw/synthesis/reimplementation-essentials.md` | Compact summary for the implementer: happy path, edge cases, dependency contracts |

Consulted (from Layer 1 raw intelligence)

| Path | What It Contains | Origin | |------|-----------------|-------------| | `workspace/raw/source/analysis/` | Source code analysis (chunk analysis, function analysis) | RAW | | `workspace/public/docs/` | Official documentation findings | PUBLIC | | `workspace/public/ecosystem/` | SDK and ecosystem analysis | PUBLIC | | `workspace/public/community/` | Community intelligence (forums, tutorials, issues) | PUBLIC | | `workspace/raw/runtime/` | Runtime observations (CLI, web UI, behavior) | RAW | | `workspace/raw/binary/` | Binary analysis findings | RAW |

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)

| Contamination | Example | Why Forbidden | |--------------|---------|---------------| | Internal function names | `parseArgs()`, `loadConfig()` | Implementation detail | | Internal variable names | `_configKey`, `configMap` | Implementation detail | | Internal class names | `ConfigLoader`, `SettingsReader` | Implementation detail | | Minified identifiers | `a()`, `x1`, `Qz`, `sp`, `r0` | Implementation detail | | Line numbers | "at line 234" | Implementation detail | | Source file paths | "in src/cli.ts" | Implementation detail | | Code structure | "calls X then Y" | Implementation detail | | Module counts | "52 modules", "8 components" | Structural leak | | IPC channel names | `task-completed`, `sync-channel` | Internal messaging | | Store property names | `store.documentBody`, `useActiveDocument` | State management internals | | Feature flag names | `FF_NEW_INDEX_FORMAT`, `ff_batch_commit_v2`, `isEnabled('feature')` | Internal gating — describe what the gate controls, not its name | | Telemetry event names | `request_rate_limited`, `job_timeout_warning` | Internal analytics — describe what is measured, not the event name | | CSS class names | `.toolbar__button`, `styled.Button` | Styling implementat