---
type: impl
description: Plan for adding the impl note type, template, relay-impl skill, and supporting changes to the Data Relay.
tags:
  - inbox
  - meta
  - knowledge-management
spec:
project:
created_at: 2026-02-11
---

## Impl Type and Relay-Impl Skill — Implementation Plan

### Goal

Add a new `impl` note type to the Data Relay for preserving concrete, code-level implementation plans — the bridge between a design doc (spec) and working code. This includes the template, a write skill, updates to existing search/list skills, and documentation changes across the vault and global config.

### Context

The Data Relay already has `docs/` for design documents (specs, architecture overviews, migration strategies). During work on the data lineage FDP subsystem, a plan was saved to a new `impls/` directory — but it used `type: doc` because no impl type existed yet. The plan had file paths, method signatures, and wiring details that made it qualitatively different from a design doc. The distinction: a doc says "what should we build and why," an impl says "here are the exact files, functions, types, and wiring."

The existing skill ecosystem follows two patterns: propose-then-act (snippets, docs) and do-then-report (commentary). Impls follow propose-then-act — March should approve before saving.

### Deliverables

#### 1. Template

**File:** `templates/impl.md`

New Obsidian template with frontmatter and canonical section structure:

- **Frontmatter fields:** `type: impl`, `description`, `tags` (with `inbox`), `spec` (optional wikilink to the design doc this implements), `project`, `created_at`
- **Sections:** Goal, Context, Deliverables (numbered, file-by-file with paths/signatures/design decisions), Files Changed (summary table), Architecture Notes (optional, Mermaid-friendly)

**Design decisions:**
- `spec:` is optional — not every impl traces back to a saved design doc. But when one exists, the traceability is valuable.
- Section structure mirrors the existing data-lineage-subsystem plan, which proved to be a natural shape for this kind of artifact.

#### 2. Skill

**File:** `skills/relay-impl/SKILL.md`

New Claude Code skill following the relay-doc pattern:

- **Name:** `relay-impl`
- **Pattern:** Propose-then-act (present to March, write only after approval)
- **Allowed tools:** Read, Write, Edit, Glob, Grep
- **Instructions:** Read tags, read template, draft plan, present for approval, write on confirmation
- **"What belongs in an impl" section** — draws the concrete line: if it doesn't have file paths and method signatures, it's a doc, not an impl
- **Quality bar:** Concrete file paths, spec citation, wikilinks, Mermaid diagrams, self-contained enough for someone to implement without the conversation

**Design decisions:**
- Included a "What belongs in an impl" section that relay-doc doesn't have, because the doc/impl boundary needs a clear decision rule. The litmus test: "does it name files and functions?"

#### 3. Migrate existing document

**File:** `impls/data-lineage-subsystem.md`

Frontmatter update only:
- `type: doc` → `type: impl`
- Add `spec:` field (empty — no saved spec exists for this plan)

#### 4. Organization taxonomy

**File:** `organization.md`

Add `impl` entry to the Directory Types section, between `doc` and `snippet`. Description captures the doc/impl distinction and the typical workflow (generated by Claude from a spec or goal, saved after approval).

#### 5. Project CLAUDE.md

**File:** `CLAUDE.md`

- Add `impls/` to write destinations, between `docs/` and `commentary`
- Update `docs/` description from "implementation documents" to "design documents" to sharpen the distinction

#### 6. Global CLAUDE.md

**File:** `~/.claude/CLAUDE.md`

- Add `impls/` to write destinations (same as project CLAUDE.md)
- Update `docs/` description (same tweak)
- Add critical reminder: "Save implementation plans — when you generate a concrete, code-level plan, propose saving it with `/relay-impl`"

#### 7. Extend search and list skills

**File:** `skills/relay-doc-search/SKILL.md`

- Search both `docs/` and `impls/` directories
- Report type (doc vs impl) in results

**File:** `skills/relay-doc-list/SKILL.md`

- List both `docs/` and `impls/` directories
- Group by type (docs first, then impls)
- Include type in per-entry output

**Design decisions:**
- Extended existing skills rather than creating separate `relay-impl-search`/`relay-impl-list`. The search use case is "find a past plan" regardless of abstraction level — splitting would force users to know which directory to search.

### Files Changed

| File | Change |
|------|--------|
| `templates/impl.md` | **New.** Obsidian template with frontmatter and canonical sections. |
| `skills/relay-impl/SKILL.md` | **New.** Propose-then-act skill for saving implementation plans. |
| `impls/data-lineage-subsystem.md` | Modified. `type: doc` → `type: impl`, added `spec:` field. |
| `organization.md` | Modified. Added `impl` to Directory Types. |
| `CLAUDE.md` | Modified. Added `impls/` write destination, sharpened `docs/` description. |
| `~/.claude/CLAUDE.md` | Modified. Added `impls/` write destination, sharpened `docs/` description, added critical reminder. |
| `skills/relay-doc-search/SKILL.md` | Modified. Now searches both `docs/` and `impls/`. |
| `skills/relay-doc-list/SKILL.md` | Modified. Now lists both `docs/` and `impls/`, grouped by type. |

### Architecture Notes

```mermaid
graph TD
    A[Design Doc<br>docs/] -->|spec: wikilink| B[Implementation Plan<br>impls/]
    B -->|informs| C[Working Code]
    D[/relay-doc/] -->|writes| A
    E[/relay-impl/] -->|writes| B
    F[/relay-doc-search/] -->|searches| A
    F -->|searches| B
    G[/relay-doc-list/] -->|lists| A
    G -->|lists| B
```