@locksmithdon/dons-flow 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 locksmithdon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,140 @@
+# @locksmithdon/dons-flow
+
+**Don's Flow v2** — a developer-specific Pi Agent workflow package that combines:
+
+- **[RPIV](https://www.npmjs.com/package/@juicesharp/rpiv-pi)** — the observable, artifact-chained delivery pipeline (`discover → research → design → plan → implement → validate → review → commit`).
+- **[Superpowers](https://github.com/obra/superpowers)** — scope control, verification-before-claims, and TDD/subagent execution patterns.
+- **A structured cycle closeout (`land`)** — the 10-step ritual that turns a verified branch into a clean, navigable, documented codebase ready for the next cycle.
+
+This package is opinionated. It assumes a particular doc layout and a particular philosophy about what belongs in the codebase vs. what belongs in the developer's tooling.
+
+> **Why v2?** The first iteration of Don's Flow was a Superpowers-based workflow with a custom landing ritual. This version integrates RPIV's observable delivery pipeline while keeping the closeout, scope-control, and learning-capture practices that made v1 work.
+
+## Install
+
+```bash
+pi install npm:@locksmithdon/dons-flow
+```
+
+This package peer-depends on RPIV, the Pi subagent runtime, and Superpowers:
+
+```bash
+pi install npm:@juicesharp/rpiv-pi
+pi install npm:@tintinweb/pi-subagents
+```
+
+Superpowers is not published to npm under a name we can resolve cleanly, so it is declared as an **optional git peer dependency** (`github:obra/superpowers`). You have three ways to satisfy it:
+
+1. **Install via your agent harness's plugin system** (most common):
+   - Claude Code: `/plugin install superpowers@superpowers-marketplace`
+   - Codex CLI: `/plugins` → search "Superpowers"
+   - Gemini CLI: `gemini extensions install https://github.com/obra/superpowers`
+   - See [obra/superpowers](https://github.com/obra/superpowers) for other harnesses.
+
+2. **Install from GitHub directly** (if your Pi/npm setup supports git URLs):
+   ```bash
+   pi install github:obra/superpowers
+   # or
+   npm install github:obra/superpowers
+   ```
+
+3. **Fork and publish under your own scope** (cleanest long-term):
+   Fork `obra/superpowers`, publish it as `@locksmithdon/superpowers`, then update this package's `peerDependencies` to point at your scoped package. This is the closest analog to how we track RPIV.
+
+If RPIV's `/rpiv-setup` command is available, it can install the RPIV sibling plugins in one go.
+
+## Relationship to Superpowers
+
+This package does not replace Superpowers. It treats Superpowers as the upstream methodology for:
+
+- `brainstorming` — Socratic design refinement before code.
+- `writing-plans` — bite-sized, code-complete implementation plans.
+- `subagent-driven-development` / `executing-plans` — task execution with review.
+- `test-driven-development` — red/green/refactor discipline.
+- `verification-before-completion` — evidence-before-claims.
+
+Where RPIV provides an equivalent or stronger mechanism, this package routes through RPIV (e.g., `discover`/`research`/`blueprint` for design and planning, `implement`/`validate` for execution). Where Superpowers has no RPIV equivalent, this package ports or keeps the Superpowers skill (e.g., `land`, `epiphany-tabling`, `capturing-learnings`).
+
+## What this package adds to RPIV
+
+RPIV gives you a strong delivery pipeline. This package adds the seams around it:
+
+| Skill | Purpose |
+|---|---|
+| `dons-flow` | The map. Tells you which skill to invoke when, and how the workflow fits together. |
+| `setup-dons-flow` | Onboarding: checks prerequisites, detects Superpowers, creates repo conventions. |
+| `land` | The 10-step cycle closeout: code review → arch review → security review → as-built docs → doc/knowledge-graph review → AGENTS.md updates → memory reconcile → retro → status review → integrate. |
+| `epiphany-tabling` | Capture mid-flight realizations in `docs/tabled.md` without derailing current work. |
+| `as-built-documentation` | Replace spec/plan scaffolding with a permanent `docs/changes/` record of what shipped. |
+| `capturing-learnings` | End-of-artifact checkpoints + the "once is a moment; twice is a pattern" promotion rule. |
+| `writing-retros` | Produce frozen retrospective documents at milestone close. |
+| `verification-before-completion` | Evidence-before-claims discipline embedded in execution. |
+| `finishing-a-development-branch` | Merge / PR / cleanup decisions at cycle end. |
+| `using-git-worktrees` | Isolated workspaces for parallel workstreams. |
+
+## The integrated workflow
+
+```
+/skill:discover "..."
+/skill:research .rpiv/artifacts/discover/<latest>.md
+/skill:blueprint .rpiv/artifacts/research/<latest>.md   # or design → plan
+/skill:implement .rpiv/artifacts/plans/<latest>.md
+/skill:validate .rpiv/artifacts/plans/<latest>.md
+/skill:code-review
+/skill:commit
+/skill:land
+```
+
+Between every major artifact, run `capturing-learnings`. During execution, keep `epiphany-tabling` active. If you stop mid-work, use `create-handoff` / `resume-handoff`.
+
+## Repo conventions
+
+This workflow expects the following project-owned files and folders in the codebase:
+
+| Path | Purpose |
+|---|---|
+| `docs/tabled.md` | Working memory for deferred ideas and follow-ups |
+| `docs/status.md` | Living status: Recently Completed, What's Next |
+| `docs/memory/` | Persistent memory entries + `MEMORY.md` index |
+| `docs/changes/` | As-built documentation: what shipped and why |
+| `docs/retros/` | Frozen retrospective documents |
+| `docs/runbooks/` | Multi-skill processes |
+| `AGENTS.md` | Repo-level agent guidance |
+
+These documents live in the codebase because they are shared context for the whole team. The skills that produce and maintain them live in this package.
+
+## Philosophy: what lives where
+
+**In the codebase (shared):**
+- The code changes.
+- As-built docs (`docs/changes/`).
+- Retros (`docs/retros/`).
+- Status, memory, and runbooks.
+
+**In this package (developer-owned):**
+- The skills and workflow conventions.
+- The closeout ritual.
+- The promotion rules for turning observations into durable artifacts.
+
+This separation lets the same workflow travel with you across repos while keeping each repo's shared knowledge in the repo.
+
+## Monitoring upstream evolution
+
+The dependency relationship with Superpowers is intentionally deferred. We review monthly whether to keep the git peer dependency, fork Superpowers, or drop it.
+
+- Memory: `docs/memory/monitor_upstream_evolution.md`
+- Runbook: `docs/runbooks/monitor-upstream-evolution.md`
+
+Set a monthly calendar reminder for the 13th, or run the runbook after every 2–3 completed projects.
+
+## Typical first use
+
+1. Install this package and its peer dependencies in a repo.
+2. Run `/skill:setup-dons-flow` to check prerequisites and scaffold repo conventions.
+3. Start a feature with `/skill:discover "[feature description]"`.
+4. When implementation is validated and reviewed, run `/skill:land` to close the cycle.
+5. After 2–3 projects, run `docs/runbooks/monitor-upstream-evolution.md` and decide whether to fork Superpowers.
+
+## License
+
+MIT

package/docs/conventions.md

@@ -0,0 +1,55 @@
+# Repo Conventions for RPIV + Superpowers Landing
+
+This workflow expects a small set of project-owned documents in every repo that uses it. These are **not** part of the `@locksmithdon/dons-flow` package; they live in the codebase because they are shared by the whole team.
+
+## Required files and folders
+
+```
+docs/
+  tabled.md              # Working memory for epiphanies and deferred work
+  tabled/                # Optional per-item tabled docs (keep .gitkeep)
+  status.md              # Living status: Recently Completed, What's Next
+  memory/
+    MEMORY.md            # Index of memory entries
+    <type>_<topic>.md    # Individual memory entries
+  changes/               # As-built documentation
+    YYYY-MM-DD-<topic>.md
+  retros/                # Frozen retrospectives
+    YYYY-MM-DD-<topic>.md
+  runbooks/              # Multi-skill processes and practices
+AGENTS.md                # Repo-level agent guidance
+```
+
+## `docs/tabled.md`
+
+Single working-memory location for epiphanies, forks, and follow-up items. Add bullet entries as they surface. Process them at end-of-artifact checkpoints and during `land` step 9. The file should end each cycle empty (or near-empty).
+
+## `docs/status.md`
+
+Living document with at least these sections:
+
+- **Recently Completed** — links to the last as-built or retro.
+- **What's Next** — highest-priority items moved from `docs/tabled.md`.
+- **Active Work** — current branch / milestone.
+
+Update during `land` step 9.
+
+## `docs/memory/`
+
+Persistent context that should carry across sessions. Keep entries short and index them in `MEMORY.md`. Memory is a thin index pointing at authoritative sources (as-builts, runbooks, code), not a duplication of them.
+
+## `docs/changes/`
+
+Permanent record of shipped work. One file per closed piece of work, written by the `as-built-documentation` skill. Specs and plans are scaffolding; as-builts are the durable reference.
+
+## `docs/retros/`
+
+Frozen retrospective documents. Once committed, a retro is not edited inline; future amendments go into a new retro.
+
+## `docs/runbooks/`
+
+Broader processes that compose multiple skills. For example, this workflow itself could be summarized as a runbook (`docs/runbooks/dons-flow.md`) if a project wants a local copy.
+
+## `AGENTS.md`
+
+Repo-level guidance for AI agents. Update only what changed during the cycle (land step 6).

package/docs/memory/MEMORY.md

@@ -0,0 +1,9 @@
+# Memory Index
+
+Cross-session context for `@locksmithdon/dons-flow`.
+
+## Entries
+
+| File | Type | Why it matters |
+|---|---|---|
+| [monitor_upstream_evolution.md](./monitor_upstream_evolution.md) | decision-deferred | We deferred choosing how to track Superpowers. Review monthly. |

package/docs/memory/monitor_upstream_evolution.md

@@ -0,0 +1,52 @@
+# Memory: Monitor RPIV and Superpowers Evolution
+
+type: decision-deferred
+cadence: monthly review
+last-reviewed: 2026-06-13
+next-review: 2026-07-13
+
+## Decision we deferred
+
+How should `@locksmithdon/dons-flow` track its upstream projects?
+
+- **RPIV** (`@juicesharp/rpiv-pi`) is published to npm and already declared as a normal peer dependency.
+- **Superpowers** (`obra/superpowers`) is a GitHub-only skills framework, not published to npm under a resolvable name. The `superpowers` name on npm is taken by an unrelated package.
+
+We are not forking or publishing Superpowers yet. Instead, we declared it as an optional git peer dependency (`github:obra/superpowers`) and will monitor both projects for 2–3 months before deciding whether to:
+
+1. Keep the optional git peer dependency.
+2. Fork Superpowers and publish it under `@locksmithdon/superpowers` as a normal npm peer dependency.
+3. Remove the Superpowers peer dependency entirely and rely on this package's ported closeout skills + RPIV's pipeline.
+4. Some hybrid we haven't thought of yet.
+
+## Why we deferred
+
+The integration is new. We want real usage data — at least 2–3 projects run through the full workflow — before committing to a maintenance-heavy fork. Premature formalization of the dependency relationship could create more work than it saves.
+
+## What to watch
+
+| Project | URL | What to check |
+|---|---|---|
+| RPIV | https://github.com/juicesharp/rpiv-mono | New skills that overlap with our closeout workflow; changes to `implement`, `validate`, `code-review`; new onboarding commands. |
+| Superpowers | https://github.com/obra/superpowers | New closeout/landing skills; npm publishing; changes to `brainstorming`, `writing-plans`, `verification-before-completion`; license changes. |
+
+## Decision criteria
+
+Fork and publish Superpowers if:
+- We find ourselves needing its upstream entry points (`brainstorming`, `test-driven-development`, `subagent-driven-development`) in projects where RPIV equivalents don't fit.
+- Superpowers still isn't on npm after 3 months of monitoring.
+- The maintenance burden of a fork feels smaller than the friction of the git dependency.
+
+Keep the git peer dependency if:
+- The optional install path works reliably across harnesses.
+- We rarely need Superpowers-specific entry points because RPIV covers the pipeline.
+
+Remove it if:
+- RPIV adds equivalent closeout/landing skills.
+- We stop using Superpowers entry points entirely.
+
+## Related
+
+- Runbook: `docs/runbooks/monitor-upstream-evolution.md`
+- Skill: `setup-dons-flow`
+- Package: `package.json` § `peerDependencies`

package/docs/runbooks/monitor-upstream-evolution.md

@@ -0,0 +1,82 @@
+# Runbook: Monitor Upstream Evolution
+
+Check RPIV and Superpowers monthly to decide how `@locksmithdon/dons-flow` should track them.
+
+## Schedule
+
+- **Cadence:** Monthly, or after every 2–3 projects completed with this workflow.
+- **Duration:** 15–30 minutes.
+- **Owner:** @locksmithdon.
+
+## Trigger
+
+- Calendar reminder on the 13th of each month.
+- After any project closeout where the dependency relationship felt awkward.
+
+## Steps
+
+### 1. Check RPIV
+
+Visit https://github.com/juicesharp/rpiv-mono and look at:
+
+- **Releases / CHANGELOG** — new versions of `@juicesharp/rpiv-pi`.
+- **Skills** — has RPIV added a `land`, `closeout`, `retro`, or `as-built` skill? If so, evaluate whether our port is still needed.
+- **Implement / validate / code-review** — have these skills changed in ways that affect our closeout sequence?
+- **Onboarding** — has RPIV added smoother setup commands we should mirror?
+
+Record findings in `docs/memory/monitor_upstream_evolution.md` under a dated heading.
+
+### 2. Check Superpowers
+
+Visit https://github.com/obra/superpowers and look at:
+
+- **Releases / RELEASE-NOTES.md** — new versions.
+- **Skills** — has Superpowers added a `land`, `closeout`, or `as-built` skill? Has it published to npm?
+- **Brainstorming / writing-plans / subagent-driven-development** — have these changed in ways that make them more or less attractive than RPIV equivalents?
+- **License** — still MIT and forkable?
+
+Record findings in `docs/memory/monitor_upstream_evolution.md` under the same dated heading.
+
+### 3. Check our own usage
+
+Review recent projects that used this workflow:
+
+- Did we use Superpowers-specific entry points (`brainstorming`, `writing-plans`, `subagent-driven-development`) or RPIV entry points (`discover`, `blueprint`, `implement`)?
+- Did the optional git peer dependency cause install friction?
+- Did RPIV's pipeline cover everything we needed?
+- Did our `land` skill feel like the right cycle boundary?
+
+Sources:
+- Recent `docs/retros/` files.
+- Recent `docs/changes/` files.
+- `docs/tabled.md` history.
+
+### 4. Decide or defer
+
+Ask:
+
+1. Is Superpowers on npm yet?
+2. Does RPIV now provide closeout/landing?
+3. Are we actively hurt by the current dependency setup?
+4. Would a fork save more friction than it costs?
+
+If the answer to any of 1–3 is **yes**, consider updating `package.json` and the workflow.
+
+If the answer is **no**, bump `next-review` by one month and keep monitoring.
+
+### 5. Capture the decision
+
+If you make a change:
+- Update `docs/memory/monitor_upstream_evolution.md`.
+- Write a brief note in `docs/changes/` if the package behavior changed.
+- Update `README.md` and `skills/dons-flow/SKILL.md` if install instructions changed.
+
+If you defer:
+- Update `last-reviewed` and `next-review` in `docs/memory/monitor_upstream_evolution.md`.
+- Add one paragraph summarizing the month's observations.
+
+## Outputs
+
+- Updated `docs/memory/monitor_upstream_evolution.md`.
+- Optional `docs/changes/` entry if the package changed.
+- Optional update to install docs.

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@locksmithdon/dons-flow",
+  "version": "2.0.0",
+  "description": "Don's Flow v2 — a developer-specific Pi Agent workflow built on RPIV's observable pipeline, Superpowers' discipline, and a structured landing closeout.",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "dons-flow",
+    "rpiv",
+    "superpowers",
+    "skills",
+    "workflow",
+    "landing",
+    "closeout"
+  ],
+  "license": "MIT",
+  "author": "locksmithdon",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/don-smith/dons-flow.git"
+  },
+  "homepage": "https://github.com/don-smith/dons-flow#readme",
+  "bugs": {
+    "url": "https://github.com/don-smith/dons-flow/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "skills/",
+    "docs/",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@tintinweb/pi-subagents": "*",
+    "@juicesharp/rpiv-pi": "*",
+    "superpowers": "github:obra/superpowers"
+  },
+  "peerDependenciesMeta": {
+    "superpowers": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "lint": "echo 'No lint configured yet'",
+    "test": "echo 'No tests configured yet'"
+  }
+}

package/skills/as-built-documentation/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: as-built-documentation
+description: Use at the end of a feature branch to create permanent as-built documentation - distills planning docs, git history, and code changes into a single reference document, then cleans up superseded plans
+---
+
+# As-Built Documentation
+
+Create a permanent "as-built" document that captures what changed, why, and what future agents/humans need to know. This replaces all planning documents with one high-signal reference.
+
+## When to Use
+
+At the end of a major piece of work, after:
+- All implementation is complete
+- Tests pass
+
+Typically invoked by the **land** skill, which determines whether as-built documentation is warranted and whether to create a new document or update an existing one.
+
+## The Process
+
+### Phase 1: Automated Discovery
+
+Gather source material from the completed work:
+
+1. **Git history**: Understand the arc of work — what was built, in what order, and any pivots or reversals.
+   - On a feature branch: `git log main..HEAD --oneline`
+   - On main: `git log --oneline` for the relevant range of commits (use planning docs and commit messages to identify the boundary)
+2. **Planning documents**: Read all docs in `docs/plans/` that relate to the completed work. These are the primary source material for synthesis.
+3. **Code changes**: Identify scope from the git history, then read the key files to understand the current architecture. Prioritize repo-level AGENTS.md files — they often capture the implementation's shape already.
+4. **Existing documentation**: Check for any other docs, comments, or READMEs that were created or modified as part of this work.
+5. **Existing as-built docs**: Check `docs/changes/` for related documents. If one exists for this area, consider updating it rather than creating a new one.
+
+### Phase 2: Synthesis
+
+Draft the as-built document following the template below. Key principles:
+
+- **Write "How It Works Now" from the code, not from plans.** Plans may be outdated. The code is the source of truth.
+- **Assess regression risk for each decision.** Ask: "How likely is it that a future agent re-proposes the rejected approach?" Rate as low/medium/high.
+  - **Low risk**: Brief rationale is sufficient
+  - **Medium risk**: Document what was rejected and why
+  - **High risk**: Explicit "why not" section with enough detail to prevent the regression
+- **Be concise.** This document should be shorter than the sum of the plans it replaces. Every sentence should earn its place.
+- **Use terms consistently.** Key concepts in the Quick Reference should match the terminology used throughout the document.
+
+### Phase 3: Clarification (if needed)
+
+If you have gaps or uncertainties that can't be resolved from code and docs alone, ask the developer targeted questions. This should be rare - most branches will have sufficient material for synthesis without intervention.
+
+### Phase 4: Write & Clean Up
+
+**Where does the as-built document go?**
+
+Documents live where their scope lives:
+- **Repo-specific work** (transforms, adapters, features within one repo) → the repo's `docs/changes/` folder
+- **Cross-repo or project-level changes** (architecture, shared conventions, infrastructure that affects all repos) → root `docs/changes/`
+
+Most as-built docs will be repo-specific. Ask: "does this document primarily help agents working in one repo, or across multiple repos?"
+
+**Creating a new document:**
+1. **Write** to `docs/changes/YYYY-MM-DD-<topic>.md` (in the appropriate repo or root)
+   - Use today's date
+   - Use a short, descriptive kebab-case topic name
+
+**Updating an existing document:**
+1. **Edit** the existing document in `docs/changes/` to incorporate the new work
+   - Update the date and Quick Reference section
+   - Revise "How It Works Now" from the current code
+   - Add any new Key Decisions
+
+**Retiring planning documents:**
+
+Planning documents from root `docs/plans/` that are repo-specific should be either:
+- **Deleted** if fully consumed into the as-built doc
+- **Moved** to the repo's `docs/` folder if they contain standing rationale that agents may need (e.g., "why we chose X over Y") but aren't linked from navigational documents
+
+Cross-repo planning documents in root `docs/plans/` should only be deleted if they've been fully superseded.
+
+**Then:**
+2. **Stage** all changes (new/updated files + deletions) with `git add`
+3. **Do NOT commit.** Leave the staged changes for the developer to review and commit.
+
+Inform the developer what was created/updated and what was deleted/moved, so they can review before committing.
+
+## Document Template
+
+```markdown
+# <Title: concise name of the change>
+
+## Quick Reference
+- **Date:** YYYY-MM-DD
+- **Key files:** <list of primary files added/modified>
+- **Key concepts:** <3-5 searchable terms>
+- **One-line summary:** <what changed and why, in one sentence>
+
+## How It Works Now
+
+<The current architectural contracts. How the pieces fit together.
+This is the section an agent reads when it needs to modify this area.
+Write from the actual code, not from planning documents.>
+
+## Key Decisions
+
+<For each major decision made during this branch:
+
+### <Decision title>
+
+**What:** <What was decided>
+**Why:** <The motivation>
+**Regression risk:** low | medium | high
+
+If medium or high risk:
+**Rejected alternative:** <What was considered and rejected>
+**Why rejected:** <Specific reasons it won't work or is worse>>
+
+## Constraints & Gotchas
+
+<Things that will bite you if you don't know about them.
+Edge cases, ordering dependencies, things that look wrong but are intentional.
+If there are none, omit this section.>
+
+## Background Context
+
+<Brief context on why this project happened at all.
+Goals, personas, acceptance criteria - only what's needed to understand the "why."
+Keep this short - a few sentences to a short paragraph.>
+```
+
+## Key Principles
+
+- **Audience is 85% AI agents, 15% humans.** Optimize for structured, parseable content with explicit terminology.
+- **Current state first, history second.** An agent reading this is usually about to modify something and needs to understand the current architecture before the backstory.
+- **Every section earns its place.** If a section would be empty or trivial, omit it.
+- **The git history of this file traces back to the original branch work.** If deeper commit-level context is ever needed, the file's own history provides the path.
+- **Plans are scaffolding, as-builts are permanent.** Don't preserve planning language or structure out of habit. Rewrite for the document's actual purpose.
+
+## Common Pitfalls
+
+| Pitfall | Instead |
+|---------|---------|
+| Copying plan content verbatim | Rewrite from the code's perspective - plans may be outdated |
+| Documenting every small decision | Focus on decisions that affect future work or have regression risk |
+| Writing for a human narrative | Structure for quick scanning - headers, lists, tables over prose |
+| Including implementation steps | The code is the implementation; document the "what" and "why," not the "how to build it" |
+| Forgetting to delete old plans | Always check `docs/plans/` for branch-related documents to remove |

package/skills/capturing-learnings/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: capturing-learnings
+description: Use at end-of-artifact checkpoints (after a spec, plan, or major commit set) and when deciding whether something observed during work should become a skill, runbook, memory entry, or be consciously dropped
+---
+
+# Capturing Learnings
+
+## Overview
+
+Observations turn into durable artifacts — skills, runbooks, memory entries — or they turn into nothing. The rule is **once is a moment; twice is a pattern.** Don't formalize on first occurrence; wait for the second sighting.
+
+This skill covers two companion practices:
+
+1. The **end-of-artifact checkpoint** — four questions we run after each approved spec, plan, or major commit set.
+2. The **promotion rule** — how we decide whether a tabled observation becomes a skill, a runbook, a memory entry, or a conscious drop.
+
+**Announce at start:** "I'm using the capturing-learnings skill to run the end-of-artifact checkpoint" or "…to decide where this learning goes."
+
+## End-of-artifact checkpoint
+
+After each approved spec, plan, or major commit set — and **before proceeding to the next artifact** — answer four questions:
+
+1. **Is the current artifact solid?** Does it include what it should? Any obvious gap or drift?
+2. **Are we carrying an assumption that hasn't been tested?** If yes, note it — ideally as a tabled entry or a memory update.
+3. **What in `docs/tabled.md` is ready to be processed?** Walk each entry; decide destination.
+4. **What should be promoted to an artifact (skill, runbook, memory) or remembered going forward?**
+5. **Any existing memory in `docs/memory/` that is now stale?** Glance through the index. If a memory's rationale has dissolved (milestone shipped, decision was reversed, scope narrowed), update or remove it. Announce the change per AGENTS.md.
+
+The checkpoint produces either (a) a concrete change (a file written, a memory updated, a skill created) or (b) an explicit "nothing to do" — never a vague promise to "come back to this later."
+
+## Promotion rule — once is a moment; twice is a pattern
+
+Premature formalization has the same cost structure as premature abstraction in code. Wait for the second sighting, then capture. Applied consistently:
+
+- **First occurrence of a pattern:** observe. Table if useful; otherwise carry on.
+- **Second occurrence:** capture as an artifact.
+
+The second sighting need not be in the same session or milestone — a tabled entry from months ago is perfectly valid as the "first" sighting when the second arrives.
+
+## Which artifact?
+
+When the second sighting arrives, match the learning to an artifact type:
+
+| Learning shape | Artifact | Where it lives | Half-life |
+|---|---|---|---|
+| A tactical, reusable how-to — the specific steps for doing one thing well (may include a script) | **Skill** | Project-local `.pi/skills/<name>/SKILL.md`, global `~/.pi/agent/skills/<name>/SKILL.md`, or an installed Pi package skill | Long — skills travel. |
+| A broader process or practice — often composing multiple skills, sometimes with its own scripts | **Runbook** | `docs/runbooks/<name>.md` | Medium — check on use; runbooks rot fast. |
+| A recurring user preference, constraint, or project context to carry across sessions | **Memory entry** | `docs/memory/<type>_<topic>.md` + index in `docs/memory/MEMORY.md` | Long — until the context shifts. |
+| A permanent record of shipped work | **As-built** | `docs/changes/YYYY-MM-DD-<topic>.md` | Permanent — frozen. See the `as-built-documentation` skill. |
+
+**Skill vs runbook — working heuristic:** a **skill** is the tactical detail: how you do one specific thing (e.g. "epiphany-tabling," "as-built-documentation," "running a particular class of query"). A **runbook** is a broader process or practice that often orchestrates multiple skills (e.g. "onboard a new agent," "release a new image") and may also carry its own scripts. Both skills and runbooks can reference or invoke scripts; the difference is scope — tactical vs. procedural.
+
+This heuristic is still being refined — we have a few of each to date and expect to recalibrate as the first runbook lands that clearly composes multiple skills. Rewrite is cheap; the important thing is to start putting these artifacts in place so the codebase becomes more navigable for AI agents and humans together.
+
+## Proliferation test
+
+**Before creating any new markdown file, ask: does the content belong in an existing document?**
+
+- If yes → extend the existing document. Add a section, a bullet, a row.
+- If no → justify the new file explicitly. Add a row to the document inventory in `docs/ways-of-working.md` in the **same change** that creates the file.
+
+Markdown sprawl is the failure mode. The inventory is the mitigation. Consolidate aggressively; delete willingly.
+
+## When NOT to capture
+
+- **The learning is truly one-off.** The second sighting hasn't arrived and is unlikely to. Drop it, or leave the tabled entry in place for later.
+- **It is already documented** somewhere appropriate (existing skill, existing runbook, an existing memory entry). Update the existing artifact rather than creating a new one.
+- **It is a mechanical constraint that can be enforced by code or CI** (lint rule, type check, validation). Encode it, don't document it — save documentation for judgment calls.
+
+## Related practices
+
+- `epiphany-tabling` — the source of most learnings this skill processes.
+- `writing-retros` — the milestone-level version of the end-of-artifact checkpoint.
+- `as-built-documentation` — the permanent artifact for a closed piece of work.