castacks · andrewjong · Aug 5, 2026 · Aug 5, 2026 · Aug 5, 2026 · Aug 5, 2026
diff --git a/.agents/skills/use-feature-notebook/SKILL.md b/.agents/skills/use-feature-notebook/SKILL.md
@@ -0,0 +1,90 @@
+---
+name: use-feature-notebook
+description: Maintain a local, gitignored notebook/ directory that records the design spec and test results for every feature an agent implements. Trigger at the START of any feature-implementation task (create notebook/NNN-feature-slug/design_spec.md before writing code), while implementing (keep the spec's per-section status labels DESIGN/TODO / WIP / DONE current), whenever tests for that feature produce output worth keeping (store under results/<section>/), and when opening the feature's PR (populate the PR body from results/results_summary.md).
+license: Apache-2.0
+metadata:
+  author: AirLab CMU
+  repository: AirStack
+---
+
+# Skill: Use the Feature Notebook
+
+## Purpose
+
+Every feature implemented by a coding agent gets a **notebook entry**: a numbered folder under `notebook/` at the repo root that holds the design spec written *before* implementation and the test results produced *during* validation. The notebook is the agent's lab journal — it captures the session context that would otherwise be lost when the conversation ends, and it is the source material for the feature's PR description.
+
+`notebook/` is **gitignored and local-only**. It never lands in a commit. Each developer's machine has its own copy. What *does* leave the machine is the distilled content: the PR body is populated from `results/results_summary.md`, and figures/tables from `results/` are attached to the PR.
+
+## Directory Layout
+
+```
+notebook/
+├── 001-add-new-planner/
+│   ├── design_spec.md              # Written BEFORE implementation
+│   └── results/
+│       ├── results_summary.md      # Written AFTER tests; feeds the PR
+│       ├── a-planner-core/         # Raw artifacts for test section (a)
+│       │   ├── run1_metrics.json
+│       │   └── trajectory_plot.png
+│       └── b-planner-hyperparameters/   # Raw artifacts for test section (b)
+│           └── sweep_table.csv
+├── 002-fix-lidar-filter/
+│   └── ...
+```
+
+Naming rules:
+
+- **Feature folder:** `NNN-short-kebab-slug`, where `NNN` is zero-padded three digits. Pick the next number by listing `notebook/` and incrementing the highest existing prefix (start at `001` if empty or missing — create `notebook/` yourself, it is not committed).
+- **Results subfolders:** one per lettered test section in `design_spec.md`, named `<letter>-<section-slug>` (e.g. section "(a) Planner core" → `results/a-planner-core/`). The letters MUST match the test-plan section letters in the spec so a reader can navigate spec ↔ results directly.
+
+## Workflow
+
+### 1. On starting a feature — write `design_spec.md`
+
+Before writing any implementation code, create `notebook/NNN-feature-slug/design_spec.md` from [assets/design_spec_template.md](assets/design_spec_template.md). It must capture:
+
+- **Problem context** — what the developer is trying to solve, in the developer's own framing from the session: motivation, constraints, prior attempts, and any decisions already made in the conversation. This is the section that preserves context which exists nowhere else.
+- **Proposed implementation** — the design: affected packages, new/changed nodes and topics, algorithms, data flow. Diagrams (mermaid) welcome. Split into subsections if the implementation has multiple parts.
+- **Test plan** — lettered sections `(a)`, `(b)`, `(c)`… each describing one validation axis: what is run (unit test, system test mark, sim scenario), what is measured, and what outcome counts as pass. These letters define the `results/` subfolder names.
+
+If the design changes materially mid-implementation, update the spec — it should describe what was actually built, with a short note on what changed and why.
+
+### 2. While implementing — keep the spec's status labels current
+
+`design_spec.md` carries an implementation status at two levels, using the values **`DESIGN/TODO`**, **`WIP`**, or **`DONE`**:
+
+- **Overall status** in the header block — the least-advanced status of any implementation section (all sections `DONE` → overall `DONE`; anything in progress → `WIP`; nothing started → `DESIGN/TODO`).
+- **Per-section status** on each Proposed Implementation subsection heading (e.g. `### 2.1 Cost-map integration — \`WIP\``) — so when the implementation has multiple parts, a reader can see exactly which parts are designed, in progress, or finished.
+
+Update the labels **as you work**, not retroactively: mark a section `WIP` when you start writing its code and `DONE` when it is implemented and building. A spec whose statuses lag reality misleads the next agent that picks up the feature.
+
+### 3. During validation — store raw results
+
+Every test run that validates the feature drops its artifacts into the matching section folder, e.g. `notebook/001-add-new-planner/results/a-planner-core/`:
+
+- Metrics files (`metrics.json`, CSVs), copied from `tests/results/<timestamp>/` when using the system test harness
+- Plots and screenshots (cross-track error curves, Foxglove/RViz captures, sim screenshots)
+- Relevant log excerpts — excerpts, not full container logs
+
+Keep raw artifacts as-produced; interpretation belongs in the summary.
+
+### 4. After validation — write `results/results_summary.md`
+
+Create `results/results_summary.md` from [assets/results_summary_template.md](assets/results_summary_template.md). One section per test-plan letter, mirroring the spec. The summary must be **self-contained**: embed the quantitative tables and qualitative figures directly in the document (markdown tables; images via relative paths like `![xte](a-planner-core/trajectory_plot.png)`) so a developer can understand the results all at once without opening the raw artifact folders. End with an overall verdict: which spec sections passed, which didn't, known limitations.
+
+### 5. On opening the PR — populate it from the notebook
+
+The PR body for the feature is built from the notebook, since reviewers cannot see `notebook/` itself:
+
+- **Motivation / context** ← `design_spec.md` problem context
+- **What changed** ← proposed implementation (as-built)
+- **Validation** ← `results_summary.md`: paste the summary tables, upload the key figures as PR attachments, and state the per-section verdicts
+
+## Pitfalls
+
+- ❌ Writing the spec after the code — the spec exists to record intent and session context before they're lost.
+- ❌ Stale status labels — a spec still marked `DESIGN/TODO` (or a section marked `WIP`) after the work shipped misleads the next reader; update statuses as you go.
+- ❌ Committing `notebook/` or referencing `notebook/...` paths from committed code, docs, or tests — it doesn't exist on other machines or in CI.
+- ❌ Results subfolder letters that don't match the spec's test-plan letters.
+- ❌ A `results_summary.md` that just links to raw files — embed the tables and figures.
+- ❌ Confusing this with [capture-discovered-knowledge](../capture-discovered-knowledge): the notebook records *per-feature* design and evidence locally; durable repo-wide knowledge still goes to AGENTS.md/skills, and module documentation still follows [update-documentation](../update-documentation).
diff --git a/.agents/skills/use-feature-notebook/assets/design_spec_template.md b/.agents/skills/use-feature-notebook/assets/design_spec_template.md
@@ -0,0 +1,58 @@
+# Design Spec: <Feature Title>
+
+> Notebook entry: `notebook/NNN-feature-slug/` · Date started: YYYY-MM-DD · Branch: `<branch-name>`
+>
+> **Status: `DESIGN/TODO`** <!-- DESIGN/TODO → WIP → DONE. Overall status = least-advanced section below. Update as you work. -->
+
+## 1. Problem Context
+
+<!-- What the developer is trying to solve, in their own framing from the session.
+     Motivation, constraints, prior attempts, decisions already made in conversation.
+     This preserves context that exists nowhere else — be generous here. -->
+
+## 2. Proposed Implementation
+
+<!-- The design: affected packages, new/changed nodes, topics/services/actions,
+     algorithms, parameters, data flow. Mermaid diagrams encouraged. If the design
+     changes during implementation, update this section and note what changed and why.
+
+     Split the implementation into subsections if it has multiple parts, and label
+     EACH subsection with its own status: DESIGN/TODO, WIP, or DONE. Update the
+     labels as implementation progresses. -->
+
+### 2.1 <Implementation part> — `DESIGN/TODO`
+
+<!-- Design for this part. -->
+
+### 2.2 <Implementation part> — `DESIGN/TODO`
+
+<!-- Design for this part. -->
+
+### Affected packages
+
+| Package | Change |
+|---------|--------|
+| `path/to/package` | ... |
+
+### Interfaces
+
+| Topic / Service / Param | Type | Direction | Purpose |
+|-------------------------|------|-----------|---------|
+| | | | |
+
+## 3. Test Plan
+
+<!-- One lettered section per validation axis. Each letter defines a results
+     subfolder: section (a) "Planner core" → results/a-planner-core/ -->
+
+### (a) <Section name>
+
+- **What is run:** <!-- unit test / system test mark / sim scenario, exact command -->
+- **What is measured:** <!-- metrics, topics, behaviors -->
+- **Pass criteria:** <!-- concrete threshold or expected behavior -->
+
+### (b) <Section name>
+
+- **What is run:**
+- **What is measured:**
+- **Pass criteria:**
diff --git a/.agents/skills/use-feature-notebook/assets/results_summary_template.md b/.agents/skills/use-feature-notebook/assets/results_summary_template.md
@@ -0,0 +1,32 @@
+# Results Summary: <Feature Title>
+
+> Spec: [`../design_spec.md`](../design_spec.md) · Date: YYYY-MM-DD · Commit tested: `<sha>`
+
+<!-- One section per test-plan letter in design_spec.md. This document must be
+     self-contained: embed tables and figures directly so a developer understands
+     the results all at once without opening the raw artifact folders. -->
+
+## (a) <Section name>
+
+**Setup:** <!-- one line: command run, sim/scenario, num robots, iterations -->
+
+| Metric | Value | Pass criterion | Pass? |
+|--------|-------|----------------|-------|
+| | | | |
+
+![description](a-section-slug/figure.png)
+
+**Interpretation:** <!-- what the numbers/figures mean; anomalies and their causes -->
+
+## (b) <Section name>
+
+...
+
+## Overall Verdict
+
+| Spec section | Verdict |
+|--------------|---------|
+| (a) ... | ✅ / ❌ |
+| (b) ... | ✅ / ❌ |
+
+**Known limitations:** <!-- what was not tested, caveats, follow-ups -->
diff --git a/.env b/.env
@@ -12,7 +12,7 @@ PROJECT_NAME="airstack"
 # If you've run ./airstack.sh setup, then this will auto-generate from the git commit hash every time a change is made 
 # to a Dockerfile or docker-compose.yaml file. Otherwise this can also be set explicitly to make a release version.
 # auto-generated from git commit hash
-VERSION="0.19.0-alpha.9"
+VERSION="0.19.0-alpha.10"
 # Choose "dev" or "prebuilt". "dev" is for mounted code that must be built live. "prebuilt" is for built ros_ws baked into the image
 DOCKER_IMAGE_BUILD_MODE="dev"  
 # Where to push and pull images from. Can replace with your docker hub username if using docker hub.

diff --git a/.gitignore b/.gitignore
@@ -94,6 +94,10 @@ simulation/ms-airsim/assets/scenes/*
 # Test results
 tests/results/
 
+# Per-feature agent notebook (design specs + test results) — local-only, feeds PR descriptions.
+# See .agents/skills/use-feature-notebook
+/notebook/
+
 # Local-only — embedded sibling repo, not part of this branch
 common/rayfronts/
 

diff --git a/AGENTS.md b/AGENTS.md
@@ -100,17 +100,37 @@ For detailed step-by-step instructions, refer to the **`.agents/skills/`** direc
 | [configure-multi-robot](.agents/skills/configure-multi-robot) | Setting up multiple robots, ROBOT_NAME namespacing, and ROS_DOMAIN_ID isolation |
 | [bump-version-and-release](.agents/skills/bump-version-and-release) | Bumping `.env` VERSION and CHANGELOG before merge to clear the version-check gate |
 | [capture-discovered-knowledge](.agents/skills/capture-discovered-knowledge) | After long context-discovery / surprising findings, persist to AGENTS.md or a new skill so the next agent doesn't redo the work |
+| [use-feature-notebook](.agents/skills/use-feature-notebook) | At the start of EVERY feature implementation: create `notebook/NNN-feature-slug/design_spec.md`, store test artifacts under `results/`, write `results/results_summary.md`, and populate the PR from it |
 
 **Agent Workflow Example:**
-1. Study reference implementation for module type
-2. Follow `add_ros2_package.md` to create package structure
-3. Implement algorithm with proper topic interfaces
-4. Follow `integrate_module_into_layer.md` to add to bringup
-5. Follow `update_documentation.md` to document
-6. Follow `debug_module.md` and `test_in_simulation.md` to verify
+1. **Create a notebook entry** — follow `use-feature-notebook` to write `notebook/NNN-feature-slug/design_spec.md` (problem context, proposed implementation, lettered test plan) before writing code
+2. Study reference implementation for module type
+3. Follow `add_ros2_package.md` to create package structure
+4. Implement algorithm with proper topic interfaces
+5. Follow `integrate_module_into_layer.md` to add to bringup
+6. Follow `update_documentation.md` to document
+7. Follow `debug_module.md` and `test_in_simulation.md` to verify, saving artifacts under `notebook/NNN-feature-slug/results/<letter>-<section>/`
+8. Write `results/results_summary.md` (embedded tables + figures) and populate the PR body from it
 
 Also see: [AI Agent Quick Guide](docs/development/ai_agent_guide.md)
 
+## Feature Notebook (`notebook/`)
+
+Every feature an agent implements gets a numbered entry under `notebook/` at the repo root — a local lab journal that survives the agent session:
+
+```
+notebook/001-add-new-planner/
+├── design_spec.md              # BEFORE coding: problem context from the session, proposed implementation, lettered test plan
+└── results/
+    ├── results_summary.md      # AFTER testing: self-contained doc with embedded tables + figures, per-section verdicts
+    ├── a-planner-core/         # Raw artifacts per test-plan section (letters match design_spec.md)
+    └── b-planner-hyperparameters/
+```
+
+`notebook/` is **gitignored — local-only on each developer's machine**. Never commit it or reference its paths from committed code. Its content leaves the machine one way: the feature's PR description is populated from `design_spec.md` (motivation, what changed) and `results_summary.md` (validation tables, figures uploaded as PR attachments).
+
+**Full workflow and templates:** [.agents/skills/use-feature-notebook](.agents/skills/use-feature-notebook)
+
 ## Reference Implementations
 
 Study these well-structured modules as examples for different types:

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Feature notebook workflow (`use-feature-notebook` skill): every agent-implemented feature gets a local, gitignored `notebook/NNN-feature-slug/` entry with a status-tracked `design_spec.md` (written before coding) and `results/` artifacts + self-contained `results_summary.md` that populate the feature's PR description
 - Battery and telemetry display in GCS RQT control panel (voltage and percentage per robot when MAVROS battery topic is bridged)
 - `TARGET_ARCH` build arg (default `x86_64`) in `Dockerfile.robot` to arch-parametrize `LD_LIBRARY_PATH`; `docker-compose.yaml` passes `TARGET_ARCH: aarch64` to the `voxl` and `l4t` real-robot image builds
 - `ros-${ROS_DISTRO}-mavros-extras` in the robot image (provides the vision_pose plugin used for external-pose deployments)

diff --git a/docs/development/index.md b/docs/development/index.md
@@ -34,6 +34,7 @@ Welcome to AirStack development! This guide will help you extend and customize t
 - **[Docker Build Profiles](intermediate/docker-build-profiles.md)** - Robot image build args and platform profiles (`robot-desktop`, `robot-l4t`, etc.)
 - **[Contributing](intermediate/contributing.md)** - Contribute to AirStack
 - **[Documentation Guide](intermediate/documentation.md)** - Write great documentation
+- **[Feature Notebook](intermediate/feature_notebook.md)** - Record design specs and test results per feature; populate PRs from them
 
 ### 🚀 Advanced Tutorials