Skip to content

Populate prawduct ai-content prompts (open-queue #2 post-#139)#200

Merged
Jason-Vaughan merged 2 commits into
mainfrom
feat/prawduct-aicontent-prompts
May 22, 2026
Merged

Populate prawduct ai-content prompts (open-queue #2 post-#139)#200
Jason-Vaughan merged 2 commits into
mainfrom
feat/prawduct-aicontent-prompts

Conversation

@Jason-Vaughan
Copy link
Copy Markdown
Owner

@Jason-Vaughan Jason-Vaughan commented May 21, 2026

What

Replaces the three placeholder prompts in data/templates/prawduct/template.json with real content. The three steps (changelog-update, learnings-capture, memory-update) shipped with empty prompt: "" strings post-Chunk-11c and surfaced as skipped rows in every V2 wrap drawer — functional, but produced no user-visible session output.

Why

Highest-leverage open-queue item per MEMORY.md boot pointer: gives V2 prawduct wraps actual CHANGELOG entries, learnings-capture, and memory-update output instead of three SKIPPED rows. The plumbing has been in place since Chunk 5 (real ai-content handler with send/poll/capture/validate); only the prompts were missing.

Validated end-to-end this morning via the V2 smoke test on prawduct-test (commits 1841083 + 9e1d79e3) — confirmed the three SKIPPED rows render correctly but produce no useful output. That gap closes here.

How

Prompt design principles:

  • AI does the gathering. Prompts instruct the AI to run git log, git diff, read CHANGELOG.md / MEMORY.md / learnings.md itself, rather than depending on TC-side prompt-interpolation expansion. Matches the ADR 0002 hybrid contract ("TC owns workflow; AI owns content"). Keeps the Chunk 5 interpolation surface unchanged (only {previousMemoryBlock} is recognized; this PR pins no-new-tokens via a test).
  • memory-update is the structured one. captureFields: ["summary", "nextSteps", "learnings"] requires the AI to emit three ## Heading blocks (case-insensitive match per _parseFields). Prompt explicitly names each heading + explains WHY (so future methodology authors don't strip the structured-response section as verbose).
  • Two free-form steps have ## Result tail discipline. changelog-update and learnings-capture have no captureFields, so the handler's ≥20-char threshold is the only validation. The ## Result heading convention gives the wrap commit body something stable to summarize and prevents AI no-ops from accidentally passing the threshold with chatter.
  • Honest no-op exit. Both free-form prompts include explicit "if there's nothing real this session, say so" guidance rather than nudging the AI to fabricate signal. Important for routine sessions.

Migration note for existing prawduct projects

The methodology template is cached at ~/.tangleclaw/templates/prawduct/template.json (via _copyBundledTemplates at lib/store.js on TC server boot). _reconcileMergeBy:id (ADR 0001) is additive-only on existing step ids, so cached templates with prompt: "" keep their empty prompts on every subsequent boot.

To pick up the populated prompts on an existing install:

  1. Stop the TC server.
  2. Delete ~/.tangleclaw/templates/prawduct/template.json (or the full ~/.tangleclaw/templates/prawduct/ directory).
  3. Restart TC. _copyBundledTemplates re-copies from data/templates/prawduct/template.json only when the cached dir is missing.

The per-project .tangleclaw/project.json is the per-project config, not the methodology template cache — deleting it does not refresh the bundled prompts. (Earlier draft of this PR pointed at the wrong file; Critic m1 caught it pre-merge.)

Alternative: wait for a future chunk that introduces per-field reconciliation of step.prompt. Tracked in .claude/plans/prawduct-aicontent-prompts.md Chunk 1 "Out of scope".

Test plan

  • 9 new tests in test/prawduct-aicontent-prompts.test.js:

    • changelog-update prompt ≥200 chars, references CHANGELOG.md / [Unreleased] / ## Result.
    • learnings-capture prompt ≥200 chars, references learnings.md / ## Result.
    • memory-update prompt ≥200 chars, mentions ## Summary / ## NextSteps / ## Learnings; captureFields lockstep.
    • Cross-cutting: every prawduct ai-content step has captureFields or ## Result tail discipline.
    • Lockstep drift guard (post-Critic): every captureField appears as ## <Field> literal in the prompt.
    • Inverse drift guard (post-Critic): every ## <Heading> in the prompt (other than ## Result) corresponds to a captureField.
    • No {...} interpolation tokens (post-Critic): pins the no-new-tokens decision.
    • _reconcileMergeBy additive-only behavior pin (post-Critic): unit test that grounds the migration note's claim.
    • Minimal-methodology empty-prompt anchor: pins that minimal's ai-content steps still ship empty so Chunk 11c contract remains exercised.
  • Full suite: 2285 / 2285 pass on this branch (was 2276 on main post-Fix tmux.createSession env vars not reaching launch command process #191; net +9).

  • Independent Critic review: YELLOW → GREEN. 1 MINOR (m1: migration recipe) + 5 NITs + 4 coverage gaps. m1 + n2 (Chunk-9 leak) + n5 (ADR Status-line chronology) + all 4 coverage-gap pins addressed in fixup commit 209ccfb. n1 (_parseFields whitespace fragility) filed as follow-up enhancement (out of scope per build plan — no handler code changes). n3 (cross-step ## Result heading is currently safe per Critic's own assessment), n4 (em-dash diff noise, cosmetic) declined.

Files touched

  • data/templates/prawduct/template.json — three ai-content step prompts populated
  • docs/adr/0002-wrap-pipeline-contract.md — Status line extension marker (post-Critic: chronologically ordered)
  • CHANGELOG.md[Unreleased] ### Changed entry with corrected migration note
  • test/prawduct-aicontent-prompts.test.js — new (9 tests, 3 describe blocks)

Out of scope

  • New interpolation tokens ({recentCommits}, {filesChanged}, {lastWrapSha}). Tracked in .claude/plans/prawduct-aicontent-prompts.md Chunk 1 "Out of scope".
  • Per-field reconciliation of step.prompt for existing projects. Same.
  • End-to-end smoke test of new prompts on a real prawduct session. Planned as Chunk 2 in the same plan file (post-merge).
  • _parseFields whitespace tolerance on heading names (Critic n1 — file as follow-up enhancement).

Replaces the three placeholder prompts in
data/templates/prawduct/template.json that surfaced as `skipped` rows in
every V2 wrap drawer post-Chunk-11c. Real prompts now instruct the AI to:

- changelog-update: edit CHANGELOG.md [Unreleased] per Keep-a-Changelog
  style with a `## Result` tail acknowledgment.
- learnings-capture: append non-obvious takeaways to
  .tangleclaw/memories/learnings.md (or write `no novel learnings` rather
  than fabricating signal).
- memory-update: write a new `Last Session` block to MEMORY.md (demoting
  the prior block to wrap-log.md) and emit `## Summary` + `## NextSteps`
  + `## Learnings` heading blocks. `_parseFields` in
  lib/wrap-steps/ai-content.js parses these against the step's
  captureFields and `_completeV2Wrap`'s summary deriver consumes
  `## Summary` for the wrap commit subject.

ADR 0002 Status line extended with the prompt-population marker.
CHANGELOG.md [Unreleased] under `### Changed` gains an entry plus the
migration note for existing prawduct projects (_reconcileMergeBy:id is
additive-only per ADR 0001 — they keep empty prompts on reconcile until
a future per-field reconciler chunk).

Tests: new test/prawduct-aicontent-prompts.test.js pins prompt
invariants (>=200 chars each, `## Summary` / `## NextSteps` /
`## Learnings` instructions in memory-update, captureFields lockstep)
and the minimal-methodology empty-prompt anchor (Chunk 11c contract
still exercised by a bundled methodology).

Full suite: 2281/2281 pass (+5 from new structural pins).
@Jason-Vaughan Jason-Vaughan added the enhancement New feature or request label May 21, 2026
m1 (MINOR — load-bearing): CHANGELOG migration recipe pointed at the
per-project `.tangleclaw/project.json` instead of the methodology
template cache `~/.tangleclaw/templates/prawduct/template.json`.
Deleting the per-project config does not refresh the cached template;
`_copyBundledTemplates` only re-copies from `data/templates/` when the
cached directory is missing. Corrected the migration paragraph to spell
out the cache location, the stop-server prerequisite, and the
copy-on-empty contract.

n2 (NIT): `learnings-capture` prompt referenced `Chunk 9` by name in
its step-5 instruction. Internal #139 sequence numbering leaks no
meaning to a future runtime AI. Removed the parenthetical; sentence is
unchanged in content.

n5 (NIT): ADR 0002 Status-line extension marker for this chunk was
inserted out of chronological order (was: 2026-05-14 ... 2026-05-21
... 2026-05-15 ... 2026-05-18). Restored to chronological order at the
end of the chain (after Chunk 10).

Coverage gaps (4 new pins in test/prawduct-aicontent-prompts.test.js):

- Lockstep: every captureField on memory-update appears as a
  `## Heading` literal in the prompt. Catches a future PR that adds
  `risks` to captureFields without adding `## Risks` to the prompt
  (would silently block every wrap).

- Inverse drift: every `## Heading` in the prompt (other than the
  free-form `## Result` tail) corresponds to a captureField. Catches
  the symmetric case — a `## Risks` block instructed but never declared
  to the parser.

- No `{...}` interpolation tokens: pins the build-plan's explicit
  out-of-scope decision (no new tokens). Prevents accidental
  introduction of `{recentCommits}` etc. that `_interpolatePrompt`
  would pass through verbatim.

- `_reconcileMergeBy` additive-only behavior pin: simulates an existing
  on-disk template with empty prompts, calls `store._reconcileMergeBy`,
  asserts `null` (no change). Grounds the CHANGELOG migration note's
  behavioral claim with a unit test.

Full suite: 2285 / 2285 pass (+9 from this chunk total).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant