# Trickle Labs Pg Trickle Pg Trickle

> Implement Roadmap Version

- Skill: `tomevault-io/trickle-labs-pg-trickle-pg-trickle` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/trickle-labs-pg-trickle-pg-trickle`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/trickle-labs-pg-trickle-pg-trickle/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/trickle-labs-pg-trickle-pg-trickle

---


# Implement Roadmap Version

Structured, self-driving workflow for implementing every item in a specific
pg_trickle release milestone. The skill continues working through items
sequentially, updates plan and roadmap status as it goes, surfaces blockers
to the user with concrete questions, and produces a completion report at the
end.

## When to Use

- Starting work on a planned milestone
- Resuming an in-progress milestone after a pause
- Verifying how far along a release is and continuing from where it left off

## Inputs to Gather First

Before any implementation begins, read these files **in parallel**:

1. `ROADMAP.md` — find the target version section: theme, item list, status
2. `plans/PLAN_0_<version_underscored>.md` — implementation order, phases,
   item IDs, effort estimates, exit criteria (if the file exists)
3. `CHANGELOG.md` (last 200 lines) — avoid re-implementing already-shipped work
4. `AGENTS.md` — coding conventions, error handling rules, SPI rules
5. `plans/INDEX.md` — cross-reference any linked sub-plans

If `plans/PLAN_0_<version_underscored>.md` does not exist, create it following
the template in [Step 1b](#step-1b--create-the-plan-file-if-missing) before
proceeding.

---

## Procedure

### Step 0 — Establish Context

Run the following in parallel:

```bash
# What version are we on?
cat pg_trickle.control | grep '^default_version'
grep '^version' Cargo.toml | head -1

# Are there uncommitted changes?
git status --short

# Which branch are we on?
git branch --show-current
```

Determine:
- **Target version** (from the argument or user's message)
- **Current version** (from `pg_trickle.control`)
- **Full details file**: `roadmap/v<VERSION>.md-full.md`
  - Example: v0.34.0 → `roadmap/v0.34.0.md-full.md`
- **Branch**: if on `main`, a new branch must be created before making any
  changes: `git checkout -b <version>-implementation`

---

### Step 1a — Parse the Full Details File

Read `roadmap/v<VERSION>.md-full.md` and extract:

1. **All item IDs and titles** (e.g. `DOG-1`, `PG17-3`)
2. **Current status** of each item in the Implementation Status table
   (⬜ Not started / 🔄 In progress / ✅ Done / ⏭ Skipped)
3. **Phase groupings** — respect the recommended implementation order
4. **Exit criteria** — the checklist at the bottom of the full details file
5. **Items already done** — skip these, but record them for the completion
   report

---

### Step 1b — Create the Full Details File if Missing

If `roadmap/v<VERSION>.md-full.md` does not exist:

1. Read the roadmap section for the target version from `ROADMAP.md`.
2. Create `roadmap/v<VERSION>.md-full.md` using this skeleton:

```markdown
> **Plain-language companion:** [v<VERSION>.md](v<VERSION>.md)

## v<VERSION> — <Theme from ROADMAP>

**Status: Planned.** Derived from [ROADMAP.md](../ROADMAP.md).

> **Release Theme**
> <one-paragraph summary>

---

### Correctness

| ID | Title | Effort | Priority |
|----|-------|--------|----------|
<rows>

### Ease of Use

| ID | Title | Effort | Priority |
|----|-------|--------|----------|
<rows>

### Test Coverage

| ID | Title | Effort | Priority |
|----|-------|--------|----------|
<rows>

---

### Recommended Implementation Order

<phases derived from roadmap items, ordered by dependency>

---

### Implementation Status

| ID | Title | Status |
|----|-------|--------|
<one row per item, all "⬜ Not started" initially>

---

### Exit Criteria

- [ ] All P0 items ✅ Done
- [ ] `just test-all` passes
- [ ] `just check-version-sync` exits 0
- [ ] CHANGELOG.md entry written
- [ ] ROADMAP.md v<VERSION> row marked ✅ Released
```

3. Also create the plain-language companion `roadmap/v<VERSION>.md` if missing.
4. Add both files to git staging:
   ```bash
   git add roadmap/v<VERSION>.md roadmap/v<VERSION>.md-full.md
   ```

---

### Step 2 — Build the Work Queue

Construct an ordered list of items to implement:

1. Take all items from the full details file in phase order.
2. **Skip** items already marked ✅ Done or ⏭ Skipped.
3. Mark the first actionable item as `🔄 In progress` in the full details file.
4. Use `manage_todo_list` to track all items, using the item ID as the todo ID.

If no items remain (all ✅ / ⏭), jump directly to [Step 6 — Completion
Report](#step-6--completion-report).

---

### Step 3 — Implement Each Item (Loop)

For each item in the work queue, repeat this inner loop:

#### 3a. Understand the Item

Read the roadmap description for the item. Identify:
- What code/SQL/test/doc changes are needed
- Which files are affected
- Whether a schema change is required (SQL migration needed)
- Dependencies on other items (check they are ✅ Done first)

If a dependency is not yet done, reorder: implement the dependency first.

#### 3b. Ask Before Ambiguous Work

**Before making any irreversible change**, if the item is ambiguous or has
multiple valid approaches, ask the user a focused question:

> "For item `<ID>` — `<title>`, I'm planning to `<approach>`. Does that match
> your intent, or should I `<alternative>`?"

Keep questions concrete and binary where possible. Never ask about more than
two items at once.

For straightforward, clearly-specified items: **do not ask — just implement**.

#### 3c. Implement

Apply changes following `AGENTS.md` conventions:

| Item type | Required steps |
|-----------|---------------|
| New Rust feature | Edit `src/`, run `just fmt`, run `just lint` |
| New SQL function | Edit `src/api/*.rs` + upgrade migration SQL + full install SQL |
| New/modified SQL | Update `sql/pg_trickle--<prev>--<cur>.sql` and `sql/pg_trickle--<cur>.sql` |
| Schema change | Require explicit user confirmation before proceeding |
| New test | Add to `tests/e2e_*_tests.rs` following naming convention |
| Documentation | Edit the relevant file in `docs/` |
| Config/GUC | Add to `src/config.rs`, document in `docs/CONFIGURATION.md` |
| Build/CI change | Edit `justfile`, `.github/workflows/*.yml`, `Dockerfile.*` |

After each item's changes are applied:
```bash
just fmt          # Always
just lint         # Must pass with zero warnings
```

For items that add or modify SQL-facing code, also run the appropriate tier:
```bash
just test-unit           # Always run after Rust changes
just test-integration    # Run if catalog or SPI changes
```

Do **not** run `just test-e2e` or `just test-all` after every item — reserve
these for phase boundaries (see Step 3e).

#### 3d. Update Status

Immediately after each item is implemented and lint passes:

1. Update the item's row in the full details file's Implementation Status table:
   `⬜ Not started` → `✅ Done`
2. If the item was in-progress (`🔄`), also update that row.
3. Update the **Status** line at the top of the full details file.

```markdown
<!-- Example update in Implementation Status table -->
| DOG-3 | Create `pgtrickle.self_monitor()` stream table | ✅ Done |
```

#### 3e. Phase Boundary Validation

At the end of each **phase** (not after every item):

```bash
just test-unit
just test-integration    # if any catalog/SPI changes in the phase
```

If tests fail:
1. Fix the failures before moving to the next phase.
2. If a failure is in pre-existing code unrelated to the current item, note it
   and ask the user: "I found a pre-existing failure in `<test>`. Should I fix
   it now or log it as a separate issue?"

---

### Step 4 — Handle Blockers

If an item cannot be implemented because:

- **Missing information**: ask the user one focused question; do not guess.
- **External dependency** (e.g. a library update, a PostgreSQL version):
  mark the item `⏭ Skipped (blocked: <reason>)` in the plan file, record
  it in the completion report, and continue with the next item.
- **Scope unclear**: present two concrete options and ask the user to choose.
- **Compilation or test failure that is not fixable within the item scope**:
  pause and ask the user for guidance before continuing.

Never silently skip items without recording the skip reason in the full details file.

---

### Step 5 — Update ROADMAP.md

After **all** items in the version are either ✅ Done or ⏭ Skipped:

1. Find the version section in `ROADMAP.md`.
2. If all required items (P0/P1) are done, update the status:
   - In the overview table: `Planned` → `✅ Released`
   - In the section heading: add `**Status: Released (<date>).**`
3. If skipped items exist, update the status to reflect the gap:
   - `**Status: Partially implemented — see plan for skipped items.**`
4. Run:
   ```bash
   just check-version-sync    # Verify version consistency
   ```

---

### Step 6 — Completion Report

After the implementation loop finishes, output a structured report:

```
## v<VERSION> Implementation Summary

### Completed (<N> items)
- ✅ <ID>: <title>
- ✅ <ID>: <title>
...

### Skipped (<N> items)
- ⏭ <ID>: <title> — <reason>
...

### Remaining work before release
1. <Exit criterion not yet met>
2. <Exit criterion not yet met>
...

### Recommended next steps
- Run `just test-e2e` to validate full E2E suite
- Run `just test-all` for final gate
- Update CHANGELOG.md with `## [<VERSION>]` entry
- Bump version: `just bump-version <VERSION>`
- Create PR using the `create-pull-request` skill
```

If all exit criteria in the full details file's checklist are met, add:

> **Release-ready.** All exit criteria satisfied. Ready for `create-pull-request`.

---

## Status Symbols

| Symbol | Meaning |
|--------|---------|
| ⬜ | Not started |
| 🔄 | In progress |
| ✅ | Done |
| ⏭ | Skipped (reason recorded) |
| ❌ | Failed / blocked |

---

## Conventions Reference (from AGENTS.md)

- No `unwrap()` or `panic!()` in non-test code
- All `unsafe` blocks must have `// SAFETY:` comments
- SPI connections are short-lived
- New SQL functions use `#[pg_extern(schema = "pgtrickle")]`
- Return `Result<T, PgTrickleError>` — convert at API boundary
- Cast `name`-typed columns to `text` in SPI queries
- Tests use Testcontainers — never a local PG instance
- Use `pgrx::log!()` / `info!()` — never `println!()`

---

## Step 7 — Maintain PLAN_OVERALL_ASSESSMENT.md

After the version implementation is complete (all items ✅ Done or ⏭ Skipped):

1. **Verify cross-references are still valid:**
   - Open `plans/PLAN_OVERALL_ASSESSMENT.md`
   - Scan all `→ Roadmap:` pointers (§2–§9 and tables §10)
   - If any roadmap items were renamed, moved between milestones, or had their
     IDs change (e.g. `EC01-1` → `EC01-2`), update the corresponding links
   - Run this check: `grep -n "→ Roadmap:" plans/PLAN_OVERALL_ASSESSMENT.md`
     and verify each link matches the current ROADMAP.md

2. **After the version ships, create a post-mortem assessment:**
   - Once v<VERSION> is released, document what was delivered vs. what slipped
   - Create or update `plans/POSTMORTEM_0_<VERSION>.md` with:
     - Which items were completed on schedule vs. late vs. skipped
     - Why items slipped (if any) — blockers, scope underestimation, etc.
     - Impact on downstream P1/P2 items (if the v<VERSION+1> roadmap needs
       rebalancing)
   - This informs prioritization of subsequent releases

3. **Note status drift:**
   - Items marked "Draft" in assessment (e.g. `PLAN_MULTI_DATABASE`,
     `PLAN_PARALLELISM`) may be promoted or deprioritized
   - After a major roadmap change, scan `plans/PLAN_OVERALL_ASSESSMENT.md`
     for references to draft plans and update them if the plans changed status
   - Example: if `PLAN_PARALLELISM` was Draft and is now actively being
     implemented in v0.22, update the assessment to reflect that

---

## Important Safeguards

- **Never drop tables or columns** without explicit user confirmation
- **Never push to `main`** directly — always work on a feature branch
- **Never run `git push --force`** without explicit user confirmation
- **Never use shell heredocs** for PR body text (Unicode corruption risk)
- **Never skip lint** — `just lint` must pass with zero warnings before
  marking any item done
- **Never mark an item done** if its associated tests are failing
- **Keep PLAN_OVERALL_ASSESSMENT.md in sync** — after major roadmap edits,
  verify all cross-references and status notes are still accurate

---
> Source: [trickle-labs/pg-trickle](https://github.com/trickle-labs/pg-trickle) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-23 -->