From df7287e0817722a3d01040a3e79c073dff768d46 Mon Sep 17 00:00:00 2001 From: Lee Overy Date: Sat, 18 Apr 2026 20:01:13 +0100 Subject: [PATCH 1/9] feat(knowledge): add workflow-knowledge SKILL.md as Layer 1 API docs Documents the knowledge CLI as the API reference loaded by Layer 2 per-phase usage guides. Covers query (single + batch), flags, search modes, output format, confidence tiers, two-step retrieval, and what not to do. Co-Authored-By: Claude Opus 4.7 (1M context) --- .tick/tasks.jsonl | 4 +- skills/workflow-knowledge/SKILL.md | 220 +++++++++++++++++++++++++++++ 2 files changed, 222 insertions(+), 2 deletions(-) create mode 100644 skills/workflow-knowledge/SKILL.md diff --git a/.tick/tasks.jsonl b/.tick/tasks.jsonl index adc3bf20..55832cb4 100644 --- a/.tick/tasks.jsonl +++ b/.tick/tasks.jsonl @@ -25,8 +25,8 @@ {"id":"tick-7d74fe","title":"Hard Stop Reference + Step 0 Integration","status":"done","priority":2,"type":"task","refs":["knowledge-base-5-1"],"description":"Problem: Entry-point skills need to gate on knowledge base readiness before proceeding. Without this gate, skills would attempt to query or index against a non-existent knowledge base. The design doc makes the knowledge base required infrastructure — no graceful degradation, just a clear hard stop with setup instructions.\n\nSolution: Create a hard stop reference file and update Step 0 in all 11 entry-point skills to run knowledge check after migrations, display the hard stop if not ready, and run knowledge compact if ready.\n\nOutcome: Every workflow invocation checks knowledge base readiness before proceeding, with a clear user-facing message when setup is needed, and automatic compaction keeping the index lean.\n\nDo:\n\nHARD STOP REFERENCE FILE:\n- Create skills/workflow-shared/references/knowledge-not-ready.md (or similar shared location — check where other shared references live).\n- This file is loaded and displayed when knowledge check returns not-ready.\n- Content should follow the existing hard stop / terminal condition conventions from CLAUDE.md:\n - Phase title box explaining what happened\n - Signpost blockquote explaining why the knowledge base is needed\n - Clear instruction: run knowledge setup to initialise\n - The exact command: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs setup\n - Brief explanation of what setup does (system config, project init, initial indexing)\n - Mention stub mode is available if no API key\n - Terminal stop — do not proceed\n- Follow the display conventions from CLAUDE.md: phase title (bullet-bordered box), signpost blockquote, rendering instructions.\n\nSTEP 0 CHANGES:\n- Update Step 0 in ALL 11 entry-point skills. The affected files:\n skills/start-feature/SKILL.md\n skills/start-epic/SKILL.md\n skills/start-bugfix/SKILL.md\n skills/start-quickfix/SKILL.md\n skills/start-cross-cutting/SKILL.md\n skills/continue-feature/SKILL.md\n skills/continue-epic/SKILL.md\n skills/continue-bugfix/SKILL.md\n skills/continue-quickfix/SKILL.md\n skills/continue-cross-cutting/SKILL.md\n skills/workflow-start/SKILL.md\n\n- The Step 0 sequence after this change:\n 1. Migrations (existing — preserve as-is)\n 2. Knowledge check: run node .claude/skills/workflow-knowledge/scripts/knowledge.cjs check and capture stdout.\n - If stdout is not-ready: load the hard stop reference file and follow its instructions. STOP — do not proceed.\n - If stdout is ready: proceed.\n 3. Knowledge compact: run node .claude/skills/workflow-knowledge/scripts/knowledge.cjs compact (no flags — not dry-run). This is silent when nothing to compact. Output only appears if chunks were removed.\n\n- The existing Step 0 structure varies between start-* and continue-* skills:\n - start-* skills CHECK if /workflow-migrate has been invoked (they expect it was already run)\n - continue-* and workflow-start ACTIVELY run migrations if not done\n The knowledge check + compact goes AFTER the migration handling in both cases. Read each skill's Step 0 to understand its current structure before modifying.\n\n- Each skill's Step 0 will need its own rendering instruction for the check result / compact output if applicable. Follow the existing conventions in each skill.\n\nALLOWED-TOOLS:\n- Add Bash(node .claude/skills/workflow-knowledge/scripts/knowledge.cjs) to the allowed-tools frontmatter of all 11 entry-point skills.\n- This follows the same pattern as the manifest CLI allowed-tools entries already in these files. Check one skill first to see the exact format.\n\nAcceptance Criteria:\n- Hard stop reference file exists and follows display conventions\n- All 11 entry-point skills have knowledge check in Step 0 after migrations\n- knowledge check returning not-ready loads the hard stop reference and stops\n- knowledge check returning ready proceeds normally\n- All 11 entry-point skills run knowledge compact after successful check\n- Compact output is visible when chunks are removed, silent when nothing to compact\n- allowed-tools frontmatter updated in all 11 entry-point skills\n- Existing migration handling in Step 0 is preserved and unmodified\n- The Step 0 ordering is: migrations -\u003e knowledge check -\u003e knowledge compact\n\nTests:\n- No automated tests for this task — it is a skill file editing task. Validation is manual:\n - Invoke a start-* skill with no knowledge base set up -\u003e verify hard stop appears\n - Invoke a continue-* skill with knowledge base set up -\u003e verify check passes and compact runs\n - Verify allowed-tools entries are present in all 11 files\n\nEdge Cases:\n- knowledge check fails with a genuine error (not not-ready, but a crash) — the skill should surface the error, not silently proceed. Check exit code: 0 is expected (ready or not-ready on stdout). Non-zero means something broke.\n- knowledge compact fails (e.g., store locked) — should surface the error but not hard-stop the workflow. Compaction failure is a warning, not a blocker. The knowledge base still works, just with stale chunks.\n- Existing Step 0 in start-* skills only checks if migrations were invoked — adding knowledge steps must not change this conditional structure. The check and compact are unconditional additions after the migration section.\n\nSpec Reference: knowledge-base/design.md — Knowledge Base is Required Infrastructure section (lines 304-320, setup flow, hard stop), Compaction Trigger section (lines 847-855, Step 0 sequence: migrations -\u003e check -\u003e compact), allowed-tools frontmatter changes (lines 728-733)","transitions":[{"from":"open","to":"in_progress","at":"2026-04-16T20:07:42Z","auto":false},{"from":"in_progress","to":"done","at":"2026-04-16T20:14:06Z","auto":false}],"parent":"tick-77697a","created":"2026-04-09T08:19:17Z","updated":"2026-04-16T20:14:06Z","closed":"2026-04-16T20:14:06Z"} {"id":"tick-055556","title":"Phase Completion Indexing","status":"done","priority":2,"type":"task","refs":["knowledge-base-5-2"],"description":"Problem: The knowledge base needs to grow automatically as workflow phases complete. Without automatic indexing at phase completion, users would need to manually run knowledge index after every discussion, research session, investigation, or specification — which would never happen consistently.\n\nSolution: Add knowledge index \u003cfile\u003e calls at the phase completion points in processing skills for all indexed phases, plus scoping (which produces a spec). Also audit the skills/ directory for every place that transitions a work unit to status: completed and add completed_at alongside each one.\n\nOutcome: Every completed workflow artifact is automatically indexed into the knowledge base, and every work unit completion path sets completed_at for the compact command's TTL calculation.\n\nDo:\n- Add knowledge index \u003cfile\u003e at the phase completion step in each of these processing skills:\n\n skills/workflow-research-process/SKILL.md\n skills/workflow-discussion-process/SKILL.md\n skills/workflow-investigation-process/SKILL.md\n skills/workflow-specification-process/SKILL.md\n skills/workflow-scoping-process/SKILL.md\n\n- For each skill, find the step where the phase artifact is finalised and committed. The index call goes AFTER the artifact is saved to disk and committed, but BEFORE any phase transition or handoff to the next phase. The artifact must exist on disk before indexing.\n\n- The index call pattern:\n Run: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs index \u003cartifact_path\u003e\n Where \u003cartifact_path\u003e is the path to the completed artifact file. Each phase has a different path convention:\n - Research: .workflows/{work_unit}/research/{topic}.md (may vary — use the actual file that was just written)\n - Discussion: .workflows/{work_unit}/discussion/{topic}.md\n - Investigation: .workflows/{work_unit}/investigation/{topic}.md\n - Specification: .workflows/{work_unit}/specification/{topic}/specification.md\n - Scoping: produces a specification — index the spec file it creates, NOT a scoping artifact (scoping is not an indexed phase per design doc)\n\n- The index call should reference the actual file path variable/value used in the skill, not a hardcoded path. Read each skill to understand how it references the artifact file.\n\n- FAILURE HANDLING: indexing failure must NOT block the phase. The artifact is already saved. If knowledge index fails, output the error message (which includes retry-failed + pending queue info from Task 4-4) and continue with the phase transition. The design doc is explicit: the phase itself is not blocked — the artifact is saved. But the failure is made visible, not silently swallowed.\n\n- MULTIPLE INDEXED ARTIFACTS: some skills may complete multiple artifacts. For example, scoping produces both a specification and potentially sets up planning. Only the spec needs indexing. Each index call is independent — a failure on one does not block the other (per design doc line 707).\n\nCOMPLETED_AT AUDIT (concrete instruction, not judgement call):\n- The completed_at field (added by the migration in Task 4-2) needs to be set going forward whenever ANY code path transitions a work unit to status: completed. Missing a path means the work unit will never expire under compaction (Task 4-5 handles missing completed_at defensively, but the result is silent non-compaction).\n- AUDIT STEP: grep the skills/ directory for every place that sets status to completed. Suggested grep patterns:\n grep -rn 'status.*completed' skills/\n grep -rn 'manifest.cjs set.*status.*completed' skills/\n grep -rn 'completed' skills/ | grep -i status\n- For EACH match, add a manifest.cjs set {work_unit} completed_at {current_date_ISO} call alongside the status-setting call. Format: YYYY-MM-DD (ISO date, same as the migration backfill in Task 4-2).\n- Known locations (verified to exist — the grep is still the authoritative source, but these are the high-traffic files):\n - skills/workflow-bridge/references/ — 5 continuation files set status: completed (bugfix-continuation.md, feature-continuation.md, epic-continuation.md, cross-cutting-continuation.md, quickfix-continuation.md). Bridge is where most feature/bugfix/quickfix completions happen — do not miss these.\n - The 5 processing skills listed above (research, discussion, investigation, specification, scoping) — conclude-*.md references\n - skills/workflow-review-process/references/review-actions-loop.md — review is often the last phase and may mark the work unit completed\n - skills/workflow-implementation-process/references/conclude-implementation.md — implementation completion\n - skills/workflow-specification-process/references/spec-completion.md and promote-to-cross-cutting.md — specification lifecycle\n - skills/workflow-scoping-process/references/write-tasks.md and write-specification.md — scoping completion paths\n - skills/workflow-start/references/manage-work-unit.md — the manage menu done action, covered by Task 5-3\n- DO NOT rely on the list above being exhaustive. The grep is the authoritative source of truth. Add completed_at setting wherever the grep finds status: completed being set, even if the file is not in the list above.\n- Report the full list of files modified (for review) when completing this task.\n- Acceptance post-condition: after editing, grep -rn 'status.*completed' skills/ should show every match adjacent (same step or reference block) to a corresponding completed_at set. This is a mechanical check the implementer can run to self-verify coverage.\n\n- Add allowed-tools for knowledge.cjs to these 5 processing skills (if not already added by Task 5-1 or Task 5-3).\n\nAcceptance Criteria:\n- Research process skill indexes the research artifact on completion\n- Discussion process skill indexes the discussion artifact on completion\n- Investigation process skill indexes the investigation artifact on completion\n- Specification process skill indexes the specification artifact on completion\n- Scoping process skill indexes the spec it produces on completion\n- Index failure does not block the phase — error is displayed, phase continues\n- Every place in skills/ that sets status: completed also sets completed_at (verified via grep audit)\n- All 5 bridge continuation files are updated (bugfix, feature, epic, cross-cutting, quickfix)\n- The list of files modified for completed_at is documented in the task completion report\n- Post-condition grep shows every status: completed match adjacent to a completed_at set\n- allowed-tools updated in all 5 processing skills\n\nTests:\n- No automated tests — skill file editing task. Validation is manual:\n - Complete a discussion in a test project -\u003e verify chunks appear in knowledge base (knowledge status shows them)\n - Complete a specification -\u003e verify chunks appear\n - Simulate index failure (e.g., corrupt store) -\u003e verify phase still completes, error is shown\n - Grep skills/ after task completion: every status-completed line should have a neighbouring completed_at line\n\nEdge Cases:\n- Scoping produces a spec but scoping itself is not an indexed phase — only the spec output is indexed. The index call must reference the spec file path, not a scoping artifact path.\n- Research in epics can produce multiple files — each file may need separate indexing. Check how the research process skill handles multiple outputs. If it produces one file per research topic, each gets its own index call.\n- completed_at audit finds a skill that doesn't import the manifest CLI — check the skill's allowed-tools and add if needed\n- Phase completion with no artifact file (edge case — should not happen in normal flow) — knowledge index will error on missing file, which is correct and visible.\n- A skill sets status: completed on a DIFFERENT work unit than its own (e.g., the manage menu) — this is covered by Task 5-3 for the manage menu specifically.\n- Bridge continuation files may set completed on a SOURCE work unit when transitioning (e.g., a feature completion closing out the feature before bridging to the next). Ensure completed_at is set on the same work unit whose status is being set.\n\nSpec Reference: knowledge-base/design.md — Indexing section (lines 337-341, primary trigger is phase completion, not mid-phase), Integration with Workflow Skills section (lines 707-708, indexing at phase completion, independent per artifact, failure does not block), completed_at field (line 824-829, set explicitly by skill at completion time going forward, the manage menu done action and any skill that sets status: completed must also set completed_at)","transitions":[{"from":"open","to":"in_progress","at":"2026-04-16T20:14:29Z","auto":false},{"from":"in_progress","to":"done","at":"2026-04-16T20:19:31Z","auto":false}],"parent":"tick-77697a","created":"2026-04-09T17:54:59Z","updated":"2026-04-16T20:19:31Z","closed":"2026-04-16T20:19:31Z"} {"id":"tick-f84af0","title":"Lifecycle Removal (Cancellation + Supersession/Promotion)","status":"done","priority":2,"type":"task","refs":["knowledge-base-5-3"],"description":"Problem: When work units are cancelled or specs are superseded/promoted, their chunks must be removed from the knowledge base. Without this, stale and contradictory information pollutes search results. Additionally, the manage menu's done action needs to set completed_at for compaction TTL calculation.\n\nSolution: Add knowledge remove calls to the manage menu reference (cancellation) and specification process (supersession/promotion) skills. Add completed_at setting to the manage menu's done action.\n\nOutcome: Work unit cancellation and spec lifecycle changes automatically clean the knowledge base, and completed work units have the timestamp needed for decay compaction.\n\nDo:\n\nCANCELLATION REMOVAL (manage menu reference):\n- The manage menu lives inside the workflow-start skill at skills/workflow-start/references/manage-work-unit.md (NOT a separate workflow-manage skill — verified).\n- Locate the cancellation action in that file (where status is set to cancelled).\n- Add inline: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs remove --work-unit {work_unit}\n- This runs INLINE as part of the cancellation action — no prompt, cancelling means done with it (design doc line 801).\n- If removal fails (store locked, CLI error): log the error visibly but do not block the cancellation. The pending queue is designed for indexing failures, not removal failures. If removal fails, output the error and note that the user can run knowledge remove manually.\n- NO frontmatter edit is needed here — skills/workflow-start is an entry-point skill that already receives allowed-tools for knowledge.cjs in Task 5-1. The reference file inherits from its parent skill.\n\nCOMPLETED_AT ON DONE ACTION (manage menu reference):\n- Locate the done/completion action in skills/workflow-start/references/manage-work-unit.md (where status is set to completed).\n- Add: manifest.cjs set {work_unit} completed_at {current_date_ISO}\n- The completed_at field is what compaction (Task 4-5) uses to calculate decay TTL. Without it, completed work units cannot expire and the index grows without bound.\n- This complements Task 5-2 which adds completed_at in processing skills and bridge continuations where completion happens automatically. The manage menu is where users manually mark work units as done — both paths must set the field.\n- Format: YYYY-MM-DD (ISO date, same as the migration backfill in Task 4-2).\n\nSUPERSESSION REMOVAL (specification process skill):\n- Find the specification process skill: skills/workflow-specification-process/SKILL.md\n- Locate the supersession action — where a spec's manifest status changes to superseded.\n- Add: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs remove --work-unit {work_unit} --phase specification --topic {topic}\n- This removes ONLY the superseded topic's spec chunks. Other topics in the same work unit (e.g., other specs in an epic) are unaffected. Granularity matters (design doc line 656).\n- The specification process skill already has allowed-tools for knowledge.cjs from Task 5-2 (for indexing). No additional frontmatter change needed.\n\nPROMOTION REMOVAL (specification process skill):\n- Locate the promotion action — where a spec's manifest status changes to promoted.\n- Add the same remove command: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs remove --work-unit {work_unit} --phase specification --topic {topic}\n- Promotion is a RELOCATION, not a deletion (design doc line 535). The chunks are removed from the original work unit. The new cross-cutting spec will be indexed naturally when it completes in the new work unit. There is a timing gap where the content is absent from the knowledge base — this is accepted per design doc line 537.\n- Research, discussion, and investigation chunks from the original work unit are KEPT — only the spec chunks are removed (design doc line 539).\n\nALLOWED-TOOLS SUMMARY FOR PHASE 5:\n- Task 5-1 adds to 11 entry-point skills (for check + compact). workflow-start is one of them, which covers the manage-work-unit.md reference file used by this task.\n- Task 5-2 adds to 5 indexed phase processing skills (for index), and updates bridge continuation files.\n- This task adds NO new allowed-tools entries — all target files are covered by Tasks 5-1 or 5-2.\n- Total Phase 5 allowed-tools changes: 16 skills (11 from 5-1 + 5 from 5-2).\n- The 3 non-indexed processing skills (planning, implementation, review) get allowed-tools in Phase 6 Task 6-2 when autonomous querying is added — no Phase 5 reason to add them now.\n- Phase entry skills (workflow-*-entry) do NOT get allowed-tools in Phase 5. The one exception is workflow-planning-entry, which gets allowed-tools in Phase 6 Task 6-3 specifically for the cross-cutting query. No other phase entry skill needs it.\n\nAcceptance Criteria:\n- Cancelling a work unit via manage menu removes its chunks from the knowledge base\n- Cancellation removal failure does not block the cancellation action\n- Manage menu done action sets completed_at on the work unit manifest\n- Superseding a spec removes only that topic's spec chunks\n- Promoting a spec removes only that topic's spec chunks from the original work unit\n- Research/discussion/investigation chunks from the same work unit survive supersession and promotion\n- No new allowed-tools frontmatter edits in this task (covered by Task 5-1 for workflow-start, Task 5-2 for specification-process)\n\nTests:\n- No automated tests — skill file editing task. Validation is manual:\n - Cancel a work unit that has indexed chunks -\u003e verify chunks are removed (knowledge status)\n - Mark a work unit as done via manage menu -\u003e verify completed_at is set in manifest\n - Supersede a spec topic in an epic -\u003e verify only that topic's spec chunks are removed, other topics and non-spec phases survive\n\nEdge Cases:\n- Cancellation of a work unit that was never indexed — knowledge remove returns 0 removed, no error. The cancellation flow should not treat this as a failure.\n- Supersession of a spec that was never indexed — same, 0 removed, no error.\n- Promotion timing gap — between removing original spec chunks and the new cross-cutting spec completing, the content is absent from the knowledge base. This is accepted per design doc.\n- Epic with multiple spec topics — superseding one MUST NOT remove others. The --topic flag ensures granularity.\n- Done action on a work unit that already has completed_at — overwrite with current date (the user is explicitly marking it done now, regardless of previous state).\n\nSpec Reference: knowledge-base/design.md — Work Unit Lifecycle section (lines 799-801, cancelled work units auto-removed, failure handling), Staleness and Supersession section (lines 530-539, superseded removed, promoted relocated, research/discussion/investigation kept), completed_at prerequisite (line 824, manage menu done action must set it), allowed-tools frontmatter changes (lines 728-733)","transitions":[{"from":"open","to":"in_progress","at":"2026-04-16T20:19:57Z","auto":false},{"from":"in_progress","to":"done","at":"2026-04-16T20:20:59Z","auto":false}],"parent":"tick-77697a","created":"2026-04-09T17:58:53Z","updated":"2026-04-16T20:20:59Z","closed":"2026-04-16T20:20:59Z"} -{"id":"tick-496c59","title":"Phase 6: Retrieval Integration","status":"open","priority":2,"refs":["knowledge-base-6"],"parent":"tick-cbbd13","created":"2026-04-09T18:09:56Z","updated":"2026-04-09T18:09:56Z"} -{"id":"tick-09d9ca","title":"Knowledge SKILL.md + Two-Step Retrieval Documentation","status":"open","priority":2,"type":"task","refs":["knowledge-base-6-1"],"description":"Problem: The knowledge base CLI exists (Phases 1-4) and is wired into skills (Phase 5), but Claude has no documentation explaining what it is, how to use it, or when to query it. Without Layer 1, Layers 2 and 3 have nothing to reference for API details.\n\nSolution: Create the knowledge skill file (SKILL.md) that serves as the API documentation layer — what commands exist, how to call them, what the output looks like, and how the two-step retrieval pattern works.\n\nOutcome: A comprehensive skill file that any processing skill can reference for knowledge base API details, enabling Claude to query the knowledge base correctly.\n\nDo:\n- Create skills/workflow-knowledge/SKILL.md following the project's skill file conventions (see CLAUDE.md Skill File Structure section).\n- This is a model-invocable skill, not user-invocable. It is loaded by reference from Layer 2 usage references (Task 6-2). It is NOT directly invoked by users.\n- Content sections:\n\n PURPOSE:\n - What the knowledge base is: a RAG system storing all workflow artifacts at full fidelity for semantic search\n - Why it exists: cross-work-unit and intra-work-unit context surfacing\n - What it indexes: research, discussion, investigation, specification (not planning, implementation, review)\n\n QUERY COMMAND:\n - Single query: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs query \u003csearch_term\u003e [flags]\n - Batch query: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs query \u003cterm1\u003e \u003cterm2\u003e [termN...] [flags]\n Multiple positional arguments run separate searches, merge results, deduplicate by chunk ID (highest score kept), apply --limit to merged set. Efficient: one store load, multiple searches.\n - Flags: --work-type, --phase, --work-unit (re-ranking hint, not filter), --limit\n - Search modes: hybrid (default when provider configured), keyword-only (when no provider)\n - Query construction guidance: use natural language, not topic slugs. Descriptive queries produce better semantic matching. Multiple queries from different angles are encouraged.\n - Example queries showing good vs poor query construction\n\n OUTPUT FORMAT:\n - Document the exact format (from design doc lines 580-603):\n [N results]\n [phase | work_unit/topic | confidence | YYYY-MM-DD]\n chunk content verbatim\n Source: source_file_path\n - Result count header, provenance line, verbatim content, source path\n - Empty results: [0 results]\n - Stub mode note when applicable: [keyword-only mode — configure embedding provider for semantic search]\n\n CONFIDENCE TIERS:\n - Explain what confidence means and how to weigh it:\n specification (high) — validated decisions, what was decided and why\n investigation (medium) — diagnostic knowledge, tied to specific symptoms\n discussion (low-medium) — conversational, may contain corrected assumptions\n research (low) — exploratory, may contain dead ends and rejected paths\n - Low confidence is not low value — research that rejected an approach prevents re-exploring dead ends\n\n TWO-STEP RETRIEVAL PATTERN:\n - Step 1: query returns chunks with provenance (lightweight, lands in context)\n - Step 2: if a chunk looks relevant, read the actual source file (source_file in metadata) for full detail\n - This keeps context lean — surface-level awareness, deep dive on demand\n - Claude should NOT read source files for every result, only when a chunk warrants deeper investigation\n\n WHAT NOT TO DO:\n - Do not dump large result sets into context speculatively\n - Do not query using topic slugs as search terms (poor semantic signal)\n - Do not query during specification phase (explicitly excluded — spec turns decisions into a golden doc, cross-cutting concerns merge at planning time)\n - Do not prepend metadata to stored content (already in enum fields)\n\nAcceptance Criteria:\n- SKILL.md exists at skills/workflow-knowledge/SKILL.md\n- Documents both single and batch query invocation forms\n- Documents all query flags and their behaviour\n- Documents the exact output format with examples\n- Documents confidence tiers with guidance on how to weigh them\n- Documents the two-step retrieval pattern (query -\u003e read source file on demand)\n- Documents what NOT to do (spec exclusion, slug queries, speculative dumps)\n- Follows project skill file conventions from CLAUDE.md\n- Can be loaded by reference from Layer 2 files (Task 6-2)\n\nTests:\n- No automated tests — documentation task. Validation is manual:\n - Read the SKILL.md and verify it provides enough information to correctly construct and interpret knowledge queries\n - Verify it follows the project's skill file structure conventions\n\nEdge Cases:\n- The SKILL.md must describe BOTH hybrid and keyword-only modes without making keyword-only feel broken — it is a supported degraded mode\n- Must not duplicate the CLI help text verbatim — this is higher-level guidance about when and why, not just how\n- Must explain that --work-unit is a re-ranking hint, not a filter — this is a common misunderstanding that would produce wrong queries if not clear\n- Batch query section must explain deduplication and merged limit behaviour\n\nSpec Reference: knowledge-base/design.md — Three-layer integration pattern (lines 716-724, Layer 1 description), Retrieved Context Format (lines 576-605, exact output format), Confidence Tiers (lines 514-525), Two-step retrieval pattern (lines 735-737), Query construction (line 737), Batch query (line 602-603, merged and deduplicated), Specification excluded from automatic retrieval (line 560)","parent":"tick-496c59","created":"2026-04-09T18:22:30Z","updated":"2026-04-09T18:30:41Z"} +{"id":"tick-496c59","title":"Phase 6: Retrieval Integration","status":"in_progress","priority":2,"refs":["knowledge-base-6"],"transitions":[{"from":"open","to":"in_progress","at":"2026-04-18T18:59:31Z","auto":true}],"parent":"tick-cbbd13","created":"2026-04-09T18:09:56Z","updated":"2026-04-18T18:59:31Z"} +{"id":"tick-09d9ca","title":"Knowledge SKILL.md + Two-Step Retrieval Documentation","status":"done","priority":2,"type":"task","refs":["knowledge-base-6-1"],"description":"Problem: The knowledge base CLI exists (Phases 1-4) and is wired into skills (Phase 5), but Claude has no documentation explaining what it is, how to use it, or when to query it. Without Layer 1, Layers 2 and 3 have nothing to reference for API details.\n\nSolution: Create the knowledge skill file (SKILL.md) that serves as the API documentation layer — what commands exist, how to call them, what the output looks like, and how the two-step retrieval pattern works.\n\nOutcome: A comprehensive skill file that any processing skill can reference for knowledge base API details, enabling Claude to query the knowledge base correctly.\n\nDo:\n- Create skills/workflow-knowledge/SKILL.md following the project's skill file conventions (see CLAUDE.md Skill File Structure section).\n- This is a model-invocable skill, not user-invocable. It is loaded by reference from Layer 2 usage references (Task 6-2). It is NOT directly invoked by users.\n- Content sections:\n\n PURPOSE:\n - What the knowledge base is: a RAG system storing all workflow artifacts at full fidelity for semantic search\n - Why it exists: cross-work-unit and intra-work-unit context surfacing\n - What it indexes: research, discussion, investigation, specification (not planning, implementation, review)\n\n QUERY COMMAND:\n - Single query: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs query \u003csearch_term\u003e [flags]\n - Batch query: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs query \u003cterm1\u003e \u003cterm2\u003e [termN...] [flags]\n Multiple positional arguments run separate searches, merge results, deduplicate by chunk ID (highest score kept), apply --limit to merged set. Efficient: one store load, multiple searches.\n - Flags: --work-type, --phase, --work-unit (re-ranking hint, not filter), --limit\n - Search modes: hybrid (default when provider configured), keyword-only (when no provider)\n - Query construction guidance: use natural language, not topic slugs. Descriptive queries produce better semantic matching. Multiple queries from different angles are encouraged.\n - Example queries showing good vs poor query construction\n\n OUTPUT FORMAT:\n - Document the exact format (from design doc lines 580-603):\n [N results]\n [phase | work_unit/topic | confidence | YYYY-MM-DD]\n chunk content verbatim\n Source: source_file_path\n - Result count header, provenance line, verbatim content, source path\n - Empty results: [0 results]\n - Stub mode note when applicable: [keyword-only mode — configure embedding provider for semantic search]\n\n CONFIDENCE TIERS:\n - Explain what confidence means and how to weigh it:\n specification (high) — validated decisions, what was decided and why\n investigation (medium) — diagnostic knowledge, tied to specific symptoms\n discussion (low-medium) — conversational, may contain corrected assumptions\n research (low) — exploratory, may contain dead ends and rejected paths\n - Low confidence is not low value — research that rejected an approach prevents re-exploring dead ends\n\n TWO-STEP RETRIEVAL PATTERN:\n - Step 1: query returns chunks with provenance (lightweight, lands in context)\n - Step 2: if a chunk looks relevant, read the actual source file (source_file in metadata) for full detail\n - This keeps context lean — surface-level awareness, deep dive on demand\n - Claude should NOT read source files for every result, only when a chunk warrants deeper investigation\n\n WHAT NOT TO DO:\n - Do not dump large result sets into context speculatively\n - Do not query using topic slugs as search terms (poor semantic signal)\n - Do not query during specification phase (explicitly excluded — spec turns decisions into a golden doc, cross-cutting concerns merge at planning time)\n - Do not prepend metadata to stored content (already in enum fields)\n\nAcceptance Criteria:\n- SKILL.md exists at skills/workflow-knowledge/SKILL.md\n- Documents both single and batch query invocation forms\n- Documents all query flags and their behaviour\n- Documents the exact output format with examples\n- Documents confidence tiers with guidance on how to weigh them\n- Documents the two-step retrieval pattern (query -\u003e read source file on demand)\n- Documents what NOT to do (spec exclusion, slug queries, speculative dumps)\n- Follows project skill file conventions from CLAUDE.md\n- Can be loaded by reference from Layer 2 files (Task 6-2)\n\nTests:\n- No automated tests — documentation task. Validation is manual:\n - Read the SKILL.md and verify it provides enough information to correctly construct and interpret knowledge queries\n - Verify it follows the project's skill file structure conventions\n\nEdge Cases:\n- The SKILL.md must describe BOTH hybrid and keyword-only modes without making keyword-only feel broken — it is a supported degraded mode\n- Must not duplicate the CLI help text verbatim — this is higher-level guidance about when and why, not just how\n- Must explain that --work-unit is a re-ranking hint, not a filter — this is a common misunderstanding that would produce wrong queries if not clear\n- Batch query section must explain deduplication and merged limit behaviour\n\nSpec Reference: knowledge-base/design.md — Three-layer integration pattern (lines 716-724, Layer 1 description), Retrieved Context Format (lines 576-605, exact output format), Confidence Tiers (lines 514-525), Two-step retrieval pattern (lines 735-737), Query construction (line 737), Batch query (line 602-603, merged and deduplicated), Specification excluded from automatic retrieval (line 560)","transitions":[{"from":"open","to":"in_progress","at":"2026-04-18T18:59:31Z","auto":false},{"from":"in_progress","to":"done","at":"2026-04-18T19:01:08Z","auto":false}],"parent":"tick-496c59","created":"2026-04-09T18:22:30Z","updated":"2026-04-18T19:01:08Z","closed":"2026-04-18T19:01:08Z"} {"id":"tick-c5a9f0","title":"Per-Phase Usage References + Contextual Query at Phase Start","status":"open","priority":2,"type":"task","refs":["knowledge-base-6-2"],"description":"Problem: Layer 1 (SKILL.md) documents the API, but Claude needs phase-specific guidance on WHEN to query and WHY — the trigger heuristics contextualised for each phase's work. Without Layer 2, Claude has the capability but not the judgment to use it effectively. Additionally, Claude needs explicit guidance on how to handle query failures — the design doc mandates pausing the workflow, not silently proceeding.\n\nSolution: Create usage reference files loaded early in processing skills that describe when and why to query during each specific phase, how to handle failures, plus the contextual query at phase start for research, discussion, and investigation.\n\nOutcome: Every processing skill loads phase-appropriate querying guidance early in its flow, the three early phases perform a contextual query at phase start, and query failures are handled by pausing with user options rather than silently skipping.\n\nDo:\n\nUSAGE REFERENCE FILES (Layer 2):\n- Create reference files — either one shared file or per-phase files, depending on how much the guidance differs between phases. The design doc (line 720) says: may be shared if guidance is generic enough, or local per phase if each needs different emphasis.\n- Recommended approach: one shared reference at skills/workflow-shared/references/knowledge-usage.md that covers the common trigger heuristics, with phase-specific notes where needed. This avoids maintaining 8 near-identical files.\n- Content:\n - Load the knowledge SKILL.md (Layer 1, Task 6-1) by reference for API details\n - Trigger heuristics — when to query (from design doc lines 551-557):\n 1. At topic boundaries — conversation edges toward adjacent territory\n 2. Upstream/downstream dependencies — current topic may affect or be affected by other work\n 3. Unfamiliar territory — not sure whether something was explored before\n 4. User prompts — user asks to check for prior context\n - Encourage proactive querying — under-querying is the bigger risk (design doc line 1003)\n - Multiple queries from different angles are expected and encouraged\n - Query construction: use natural language derived from what is currently being discussed, not topic names\n - Two-step retrieval reminder: query first (lightweight), read source file only when a chunk warrants investigation\n\nQUERY FAILURE HANDLING (from design doc lines 767-776):\n- This is skill-level behavior, not CLI behavior. The CLI retries 3 times and then exits with a non-zero code and error message (Task 4-4). The SKILL must handle what happens next:\n 1. If knowledge query fails (non-zero exit): PAUSE the workflow. Do not silently proceed without context.\n 2. Present the error clearly: what failed, likely causes (API key expired, network down, store corrupted).\n 3. Offer the user two options: fix the issue and retry, or explicitly choose to proceed without knowledge context.\n 4. If the user chooses to proceed: continue the phase but note that knowledge retrieval was skipped. This note should be visible in the output so the user knows context may be missing.\n- The design doc is emphatic: the value of the knowledge base is too high to silently skip (line 776).\n- This failure handling guidance goes in the usage reference (Layer 2) so it applies to all phases that load it.\n\n- Phase-specific notes within the shared reference (or in separate files if warranted):\n - Research: query at start + throughout. Early phase, high chance of overlap with prior work.\n - Discussion: query at start + throughout. Decisions being made that may relate to prior decisions.\n - Investigation: query at start + throughout. Symptoms and root causes may have been seen before.\n - Specification: EXCLUDED from automatic retrieval. Explicit note: do not query during spec authoring. Cross-cutting concerns merge at planning time, not spec time (design doc line 560).\n - Scoping: query throughout. Quick-fix scoping benefits from knowing if the issue was discussed elsewhere.\n - Planning: query throughout, especially for cross-cutting context. The explicit cross-cutting query is handled separately (Task 6-3).\n - Implementation: query when hitting unfamiliar territory or when a task touches areas covered by prior work.\n - Review: query to verify decisions against prior context.\n\nCONTEXTUAL QUERY AT PHASE START:\n- Add to the processing skills for research, discussion, and investigation: at the beginning of the phase (after loading references, before the first substantive step), construct a natural language query from available context and search the knowledge base.\n- Available context for query construction (from design doc line 549): topic description, bootstrap answers, handoff context, problem statement — whatever is available at that point.\n- NOT the topic slug. The query must be descriptive: not auth-flow but user authentication flow using OAuth2 with PKCE for mobile and web clients.\n- Returns a small, focused result set. Zero cost if nothing comes back. High value when it catches prior work.\n- This is a single query, not a dump. If results come back, Claude reads them and proceeds with that context. If nothing comes back, proceed as normal.\n- Specification is EXCLUDED — no contextual query at spec phase start.\n\nLOAD DIRECTIVES IN PROCESSING SKILLS:\n- Add a load directive for the usage reference early in each processing skill (alongside where case conventions are loaded). The exact insertion point varies per skill — read each to find the right place.\n- Processing skills that need this:\n skills/workflow-research-process/SKILL.md\n skills/workflow-discussion-process/SKILL.md\n skills/workflow-investigation-process/SKILL.md\n skills/workflow-scoping-process/SKILL.md\n skills/workflow-planning-process/SKILL.md\n skills/workflow-implementation-process/SKILL.md\n skills/workflow-review-process/SKILL.md\n- Specification process does NOT load the usage reference (excluded from automatic retrieval).\n\nALLOWED-TOOLS FOR REMAINING PROCESSING SKILLS:\n- Add Bash(node .claude/skills/workflow-knowledge/scripts/knowledge.cjs) to:\n skills/workflow-planning-process/SKILL.md\n skills/workflow-implementation-process/SKILL.md\n skills/workflow-review-process/SKILL.md\n- These 3 were deferred from Phase 5 — now they need it for autonomous querying.\n- Scoping process already has it from Phase 5 Task 5-2. Research, discussion, investigation, specification process already have it from Task 5-2.\n\nAcceptance Criteria:\n- Usage reference file(s) exist with trigger heuristics and phase-specific guidance\n- Usage reference loads Layer 1 (SKILL.md) by reference for API details\n- Query failure handling documented: pause workflow, present error, offer user choice to proceed or fix\n- All 7 processing skills (except specification) load the usage reference early in their flow\n- Specification process does NOT load the usage reference\n- Research, discussion, and investigation processing skills perform a contextual query at phase start\n- Contextual query uses descriptive natural language, not topic slugs\n- allowed-tools added to planning, implementation, and review processing skills\n- Trigger heuristics match the design doc (topic boundaries, dependencies, unfamiliar territory, user prompts)\n\nTests:\n- No automated tests — skill file editing task. Validation is manual:\n - Start a discussion in a test project with existing indexed knowledge -\u003e verify contextual query runs and surfaces relevant prior work\n - Start a specification -\u003e verify no contextual query runs\n - Simulate query failure -\u003e verify workflow pauses with user options (not silent skip)\n - Verify all processing skills load the usage reference\n\nEdge Cases:\n- Contextual query with no prior knowledge indexed — returns [0 results], phase proceeds normally with no delay or noise\n- Phase start with very little context available (e.g., just a topic name) — construct the best query possible from what is available. A poor query that returns nothing is fine. The design doc accepts zero cost if nothing comes back.\n- Query failure during contextual query at phase start — same failure handling applies (pause, present, offer choice). The contextual query is not exempt from failure handling.\n- Shared vs per-phase reference: if a shared reference becomes unwieldy with too many phase-specific notes, split into per-phase files. Start shared, split if needed.\n\nSpec Reference: knowledge-base/design.md — Three-layer integration pattern (lines 716-724, Layer 2 description), Autonomous querying trigger heuristics (lines 551-557), Contextual query at phase start (line 549), Specification excluded (line 560), Query Failures section (lines 767-776, pause workflow, present error, user choice), Autonomous query guardrails review finding #16 (line 1002)","parent":"tick-496c59","created":"2026-04-09T18:23:15Z","updated":"2026-04-09T18:30:02Z"} {"id":"tick-2841d6","title":"Inline Callouts + Planning Entry Cross-Cutting Query","status":"open","priority":2,"type":"task","refs":["knowledge-base-6-3"],"description":"Problem: Layer 2 provides general guidance loaded once at the start of a phase, but Claude can lose awareness of the knowledge base as a conversation develops. Layer 3 addresses this with targeted nudges at specific moments where querying is most valuable. Additionally, the planning entry skill has an existing manual approach for cross-cutting context that should be replaced with a targeted semantic query.\n\nSolution: Add inline callouts at pertinent points in processing skills and replace the planning entry cross-cutting context approach with a knowledge base query.\n\nOutcome: Claude gets timely reminders to check the knowledge base at high-value moments, and planning entry uses semantic search instead of manually reading every cross-cutting spec.\n\nDo:\n\nINLINE CALLOUTS (Layer 3):\n- Add brief reminders within the step flow of processing skills at moments where the knowledge base is most valuable. These are nudges, not full reference loads — same pattern as existing callouts for review agents and commit reminders (design doc line 722).\n- Format: a short inline note like: Consider querying the knowledge base — this subtopic may have been explored in prior work. Or: If this constraint seems familiar, check the knowledge base for prior decisions.\n- Placement is judgment-based — read each processing skill and identify moments where:\n - A complex subtopic is being explored\n - A decision is being made that could conflict with prior work\n - An assumption is being introduced that may have been validated or rejected before\n - The conversation moves to adjacent territory\n- Processing skills to add callouts to (all except specification):\n skills/workflow-research-process/SKILL.md — when exploring new directions, before concluding\n skills/workflow-discussion-process/SKILL.md — when discussing options, before deciding\n skills/workflow-investigation-process/SKILL.md — when analysing root causes\n skills/workflow-scoping-process/SKILL.md — when scoping constraints\n skills/workflow-planning-process/SKILL.md — when designing phases/tasks that touch other areas\n skills/workflow-implementation-process/SKILL.md — when hitting unfamiliar code areas\n skills/workflow-review-process/SKILL.md — when verifying decisions against original intent\n- These are 1-2 line callouts embedded at specific step boundaries, NOT new steps or reference loads. They should feel natural, not interruptive.\n- Do NOT add callouts to the specification process — specification is excluded from automatic retrieval.\n\nPLANNING ENTRY CROSS-CUTTING QUERY:\n- This replaces existing functionality in skills/workflow-planning-entry/references/cross-cutting-context.md (design doc line 562).\n- The current approach: reads every cross-cutting specification and manually assesses relevance to the current topic. This is expensive (loads all cross-cutting specs into context) and keyword-dependent (misses semantic connections).\n- The replacement: a targeted semantic query filtered to work_type: cross-cutting.\n node .claude/skills/workflow-knowledge/scripts/knowledge.cjs query \u003ctopic_description\u003e --work-type cross-cutting --limit 10\n- The query term should be constructed from the current topic's specification summary or description — not the topic name.\n- Results are cross-cutting specs that are semantically relevant to the current plan. Claude reads the results, identifies applicable cross-cutting decisions, and incorporates them into the planning context.\n- This is a deterministic step replacing existing functionality, not a speculative search (design doc line 726).\n- Update or replace cross-cutting-context.md to use the knowledge query instead of manual spec reading.\n- Ensure skills/workflow-planning-entry/SKILL.md has allowed-tools for knowledge.cjs if not already present (it may have been added as an entry-point skill in Task 5-1, but planning-entry is a phase entry skill, not an entry-point skill — check).\n\nAcceptance Criteria:\n- Inline callouts exist at pertinent points in 7 processing skills (all except specification)\n- Callouts are brief nudges (1-2 lines), not full reference loads\n- Callouts are placed at high-value moments identified by reading each skill's flow\n- Specification process has NO callouts\n- Planning entry cross-cutting query replaces the manual approach in cross-cutting-context.md\n- Cross-cutting query uses --work-type cross-cutting filter\n- Cross-cutting query uses descriptive topic text, not topic slug\n- Planning entry has allowed-tools for knowledge.cjs\n\nTests:\n- No automated tests — skill file editing task. Validation is manual:\n - Read processing skills and verify callouts are placed at high-value moments\n - Start planning for a topic with existing cross-cutting specs indexed -\u003e verify the query surfaces relevant cross-cutting decisions\n - Verify the old manual cross-cutting spec reading approach is replaced, not duplicated\n\nEdge Cases:\n- Planning entry cross-cutting query when no cross-cutting specs are indexed — returns [0 results], planning proceeds without cross-cutting context (same as today when no cross-cutting specs exist)\n- Callout placement in skills with varying step structures — read each skill carefully, do not add callouts at the same structural position in every skill. Placement is semantic, not mechanical.\n- The planning-entry skill is a phase entry skill (internal, user-invocable: false), not an entry-point skill. It was NOT updated in Task 5-1 (which targeted start-*/continue-* skills). It needs allowed-tools for the cross-cutting query added here.\n\nSpec Reference: knowledge-base/design.md — Three-layer integration pattern (lines 716-724, Layer 3 description — inline callouts same pattern as review agents and commit reminders), Planning entry cross-cutting query (line 562, replaces existing manual approach, filtered to work_type: cross-cutting), and the note that this is a deterministic step replacing existing functionality (line 726)","parent":"tick-496c59","created":"2026-04-09T18:23:50Z","updated":"2026-04-09T18:23:50Z"} {"id":"tick-2e511f","title":"Phase 7: Setup Wizard","status":"open","priority":2,"refs":["knowledge-base-7"],"parent":"tick-cbbd13","created":"2026-04-09T19:04:09Z","updated":"2026-04-09T19:04:09Z"} diff --git a/skills/workflow-knowledge/SKILL.md b/skills/workflow-knowledge/SKILL.md new file mode 100644 index 00000000..6846ecaa --- /dev/null +++ b/skills/workflow-knowledge/SKILL.md @@ -0,0 +1,220 @@ +--- +name: workflow-knowledge +user-invocable: false +allowed-tools: Bash(node .claude/skills/workflow-knowledge/scripts/knowledge.cjs) +--- + +# Workflow Knowledge + +CLI tool for querying the workflow knowledge base — a retrieval-augmented store of all completed workflow artifacts, searchable by semantics or keyword. This file is the API documentation layer. Load it when you need to construct a query or interpret results. + +## What the knowledge base is + +A local semantic-search index over every completed research, discussion, investigation, and specification artifact in `.workflows/`. Content is stored at full fidelity — chunks are the actual text, not summaries — with provenance metadata attached: which work unit, which phase, which topic, when it was indexed. + +**Why it exists**: to surface prior context that would otherwise be lost across work units or forgotten within one. A spec written three months ago, a discussion that rejected an approach, an investigation that ruled out a cause — all remain queryable. + +**What is indexed**: + +- `research` (low confidence — exploratory, may contain dead ends) +- `discussion` (low-medium — conversational, may contain corrected assumptions) +- `investigation` (medium — diagnostic, tied to specific symptoms) +- `specification` (high — validated decisions, "what we decided to build") + +**What is NOT indexed**: planning, implementation, review. These phases describe execution, not knowledge. Searching them would surface task IDs and code fragments, not insight. + +--- + +## Invocation + +```bash +node .claude/skills/workflow-knowledge/scripts/knowledge.cjs [args] +``` + +Every skill that calls this must declare `Bash(node .claude/skills/workflow-knowledge/scripts/knowledge.cjs)` in its `allowed-tools` frontmatter. + +--- + +## `query` — search the knowledge base + +### Single query + +```bash +node .claude/skills/workflow-knowledge/scripts/knowledge.cjs query "" [flags] +``` + +### Batch query + +```bash +node .claude/skills/workflow-knowledge/scripts/knowledge.cjs query "" "" "" [flags] +``` + +Multiple positional arguments run separate searches in one invocation, merge the results, deduplicate by chunk ID (highest score wins), then apply `--limit` to the merged set. Efficient — one store load, multiple searches. Encouraged when you want to attack the same topic from different angles. + +### Flags + +| Flag | Behaviour | +|------|-----------| +| `--work-type ` | Filter results to a work type. Comma-separated list accepted (e.g., `--work-type cross-cutting` or `--work-type epic,feature`). Hard filter — non-matching chunks are excluded | +| `--phase ` | Filter to one or more phases. Same comma-separated syntax. Hard filter | +| `--topic ` | Filter to one or more topics. Same comma-separated syntax. Hard filter | +| `--work-unit ` | **Re-ranking hint, NOT a filter.** Boosts chunks from this work unit in post-processing. Cross-work-unit results still appear, just ranked lower. Use it to say "I'm currently working in `auth-flow`, prefer its context" — not to exclude other work | +| `--limit ` | Cap result count after merge + re-rank. Default 10 | + +### Search modes + +Two modes, auto-selected based on project config: + +- **Hybrid** (default when an embedding provider is configured): keyword + vector search combined, results re-ranked by work-unit proximity, confidence tier, and recency. +- **Keyword-only** (when no provider is configured): full-text search only. Still useful — you lose semantic expansion but exact-term queries work. The output prepends a note: `[keyword-only mode — configure embedding provider for semantic search]`. This is a supported degraded mode, not a broken state. + +### Query construction + +Use **natural language**, not topic slugs. A query is a short description of what you're looking for, framed the way the original author would have written about it. + +- Good: `"OAuth2 PKCE flow for mobile clients"` +- Good: `"why we ruled out email as a primary identity field"` +- Poor: `"auth-flow"` (topic slug — weak semantic signal) +- Poor: `"auth"` (too broad — matches everything auth-related) + +Descriptive, specific, phrased in the language likely to appear in the source material. Multiple queries from different angles are encouraged — one for the decision, one for the constraint, one for the rejected alternative. + +### Output format + +``` +[3 results] + +[specification | auth-flow/auth-flow | high | 2026-03-15] +User identity uses UUID v7. Email is a profile attribute, not an identifier. +Source: .workflows/auth-flow/specification/auth-flow/specification.md + +[discussion | payments-overhaul/data-model | low-medium | 2026-03-10] +Debated UUID vs email for identity. UUID won because email changes are common. +Source: .workflows/payments-overhaul/discussion/data-model.md + +[research | payments-overhaul/exploration | low | 2026-02-28] +Explored identity approaches. Email-based ruled out due to GDPR right-to-erasure. +Source: .workflows/payments-overhaul/research/exploration.md +``` + +- **Header line**: `[N results]` where N is the merged, deduplicated, re-ranked count after `--limit`. +- **Provenance line** (per chunk): `[phase | work_unit/topic | confidence | YYYY-MM-DD]`. Date is the indexing timestamp, approximating when the knowledge was produced. +- **Content**: the chunk text verbatim. No summarisation, no truncation. +- **Source line**: the path to the source artifact. Use this with the two-step retrieval pattern below. +- **Blank line** between chunks. +- **Empty results**: `[0 results]` — no provenance lines, nothing else. Treat as "no prior context found" — move on. +- **Stub-mode note** (when applicable): prepended as the first line before the header — `[keyword-only mode — configure embedding provider for semantic search]`. + +### Confidence tiers — how to weigh results + +Confidence is intrinsic to the source phase. It tells you how much weight to give the content, not whether to use it. + +| Tier | Meaning | +|------|---------| +| `high` | Specification — a decision that was validated and written down. Trust the *what*, verify the *why* against the source if it matters | +| `medium` | Investigation — diagnostic work tied to specific symptoms. Trust the diagnosis, but check whether the symptom is still current | +| `low-medium` | Discussion — conversational, may contain assumptions that were corrected later in the same file. Read for context, not conclusions | +| `low` | Research — exploratory. May be a dead end, a rejected path, or an unvalidated idea | + +**Low confidence is not low value.** A research chunk that rejected an approach prevents the next work unit from re-exploring the same dead end. A discussion chunk showing a corrected assumption explains *why* the spec says what it says. Don't filter out low-confidence results — weigh them. + +### Two-step retrieval pattern + +1. **Query** returns chunks with provenance. Lightweight — lands in your context window. +2. **Read the source file** (from the `Source:` line) only if a chunk looks load-bearing for what you're doing. + +Don't read source files for every result. Most queries produce a couple of chunks that are mildly relevant and one that's directly relevant — read the one, skim the rest from the chunk text alone. This keeps context lean while preserving full-fidelity access on demand. + +### What NOT to do + +- **Do not dump large result sets speculatively.** `--limit 50` with a vague query produces noise. Prefer a focused query with the default limit. +- **Do not use topic slugs as search terms.** `"auth-flow"` is a weak semantic signal. Describe the thing, don't name it. +- **Do not query during the specification phase.** Spec turns discussion decisions into a golden document. Cross-cutting concerns merge at planning time via an explicit cross-cutting query, not during spec authoring. Querying mid-spec pulls the spec away from its own source material. +- **Do not prepend metadata to the query string.** The CLI already filters by `work_type`, `phase`, `topic`, `work_unit` via flags. `"auth-flow specification UUID identity"` is worse than `"UUID identity"` with `--phase specification`. +- **Do not treat `--work-unit` as a filter.** It re-ranks. If you want to exclude other work units, you probably don't — cross-work-unit context is the point of the knowledge base. + +--- + +## `check` — readiness probe + +```bash +node .claude/skills/workflow-knowledge/scripts/knowledge.cjs check +``` + +Exit code is always `0` (unless the filesystem itself is unreadable). Output on stdout: + +- `ready` — knowledge base is initialised and the store is loadable +- `not-ready` — missing directory, missing config, missing store, or unloadable store + +Skills branch on the stdout string, not the exit code. Used in Step 0 of entry-point skills to detect an uninitialised knowledge base and direct the user to `knowledge setup`. + +--- + +## `index` — write to the store + +```bash +# Single artifact (used by phase-completion steps) +node .claude/skills/workflow-knowledge/scripts/knowledge.cjs index + +# Bulk catch-up (no args — finds all unindexed completed artifacts) +node .claude/skills/workflow-knowledge/scripts/knowledge.cjs index +``` + +- **With a file**: re-indexing replaces existing chunks for that file (idempotent). The path must match `.workflows/{work_unit}/{phase}/...` so identity can be derived. +- **Without args**: discovers every completed artifact across all work units and indexes anything missing. Used by setup and manual catch-up. +- Failures are retried (exponential backoff). Files that still fail are pushed to a pending queue and retried on the next `index` call. +- Exits non-zero if the file doesn't exist or the path can't be parsed. + +Typically invoked by processing skills at phase completion — not queried by Claude during a phase. + +--- + +## `remove` — remove chunks + +```bash +node .claude/skills/workflow-knowledge/scripts/knowledge.cjs remove --work-unit [--phase

] [--topic ] +``` + +Removes chunks matching the given filter. Granularity: + +- `--work-unit ` alone — removes every chunk for that work unit +- `--work-unit --phase

` — narrows to one phase +- `--work-unit --phase

--topic ` — narrows to one topic + +Used when a spec is superseded or promoted, when a work unit is cancelled, or when catching up after a manifest change. `--topic` requires `--phase`. + +Output: `Removed N chunks for {scope}`. Exits non-zero on usage errors. + +--- + +## `status` — full health report + +```bash +node .claude/skills/workflow-knowledge/scripts/knowledge.cjs status +``` + +Human-readable report of the store's state: chunk counts by work unit, phase, and work type; last-indexed timestamp; provider info; pending queue; provider-mismatch warnings; orphan detection; unindexed completed artifacts; manifest-knowledge consistency checks. Not used in skill automation — intended for debugging and user inspection. + +--- + +## `rebuild` and `compact` — maintenance commands + +- **`rebuild`** — destructive. Deletes the existing index and re-indexes all completed artifacts. Prompts the user to type `rebuild` literally to confirm. **Human-only** — Claude cannot run it (interactive prompt). Non-deterministic: rebuilt chunks won't match the originals (embedding variance, edited artifacts). +- **`compact [--dry-run]`** — removes chunks from work units whose `completed_at` date exceeds the configured `decay_months` TTL. Specifications are exempt. `--dry-run` previews without deleting. + +Skills do not call these directly during normal operation. Users run them manually. + +--- + +## `setup` — interactive wizard + +Not yet implemented (stub — Phase 7 of the knowledge base rollout). When available, it will handle system config, project init, and initial indexing in one flow. **Human-only** — interactive prompts. If `knowledge check` returns `not-ready`, direct the user to run `knowledge setup` rather than trying to fix it programmatically. + +--- + +## Exit codes + +- `0` — success, or `check` reporting either state +- Non-zero — usage error, file not found, unparseable path, lock contention exceeded, or unrecoverable provider mismatch + +`query` with zero results exits `0` and prints `[0 results]`. `check` exits `0` for both `ready` and `not-ready`. Both semantics are intentional — skills branch on output, not on the exit code. From 659e0aaf3f00236a032fd958d3c343dbc0c8a395 Mon Sep 17 00:00:00 2001 From: Lee Overy Date: Sat, 18 Apr 2026 20:10:24 +0100 Subject: [PATCH 2/9] feat(knowledge): wire Layer 2 knowledge usage into processing skills MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds shared references for autonomous knowledge querying: - knowledge-usage.md: trigger heuristics, query construction, failure handling (pause-with-options), phase-specific notes - contextual-query.md: single query at research/discussion/ investigation phase start Wires the refs into all processing skills (except specification — explicitly excluded from automatic retrieval). Adds knowledge.cjs to allowed-tools on planning, implementation, and review. Renumbers downstream steps and internal routing. Co-Authored-By: Claude Opus 4.7 (1M context) --- .tick/tasks.jsonl | 2 +- skills/workflow-discussion-process/SKILL.md | 60 +++++++++-- .../references/conclude-discussion.md | 2 +- .../references/final-review.md | 6 +- .../workflow-implementation-process/SKILL.md | 43 +++++--- .../references/analysis-loop.md | 8 +- .../references/conclude-implementation.md | 2 +- .../references/task-loop.md | 2 +- .../workflow-investigation-process/SKILL.md | 68 ++++++++++--- .../references/conclude-investigation.md | 2 +- .../references/synthesis-agent.md | 2 +- skills/workflow-planning-process/SKILL.md | 51 +++++++--- .../references/conclude-plan.md | 2 +- skills/workflow-research-process/SKILL.md | 44 ++++++++- .../references/final-review.md | 6 +- skills/workflow-review-process/SKILL.md | 43 +++++--- .../references/produce-review.md | 2 +- skills/workflow-scoping-process/SKILL.md | 45 ++++++--- .../references/contextual-query.md | 56 +++++++++++ .../references/knowledge-usage.md | 99 +++++++++++++++++++ 20 files changed, 455 insertions(+), 90 deletions(-) create mode 100644 skills/workflow-shared/references/contextual-query.md create mode 100644 skills/workflow-shared/references/knowledge-usage.md diff --git a/.tick/tasks.jsonl b/.tick/tasks.jsonl index 55832cb4..6c785366 100644 --- a/.tick/tasks.jsonl +++ b/.tick/tasks.jsonl @@ -27,7 +27,7 @@ {"id":"tick-f84af0","title":"Lifecycle Removal (Cancellation + Supersession/Promotion)","status":"done","priority":2,"type":"task","refs":["knowledge-base-5-3"],"description":"Problem: When work units are cancelled or specs are superseded/promoted, their chunks must be removed from the knowledge base. Without this, stale and contradictory information pollutes search results. Additionally, the manage menu's done action needs to set completed_at for compaction TTL calculation.\n\nSolution: Add knowledge remove calls to the manage menu reference (cancellation) and specification process (supersession/promotion) skills. Add completed_at setting to the manage menu's done action.\n\nOutcome: Work unit cancellation and spec lifecycle changes automatically clean the knowledge base, and completed work units have the timestamp needed for decay compaction.\n\nDo:\n\nCANCELLATION REMOVAL (manage menu reference):\n- The manage menu lives inside the workflow-start skill at skills/workflow-start/references/manage-work-unit.md (NOT a separate workflow-manage skill — verified).\n- Locate the cancellation action in that file (where status is set to cancelled).\n- Add inline: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs remove --work-unit {work_unit}\n- This runs INLINE as part of the cancellation action — no prompt, cancelling means done with it (design doc line 801).\n- If removal fails (store locked, CLI error): log the error visibly but do not block the cancellation. The pending queue is designed for indexing failures, not removal failures. If removal fails, output the error and note that the user can run knowledge remove manually.\n- NO frontmatter edit is needed here — skills/workflow-start is an entry-point skill that already receives allowed-tools for knowledge.cjs in Task 5-1. The reference file inherits from its parent skill.\n\nCOMPLETED_AT ON DONE ACTION (manage menu reference):\n- Locate the done/completion action in skills/workflow-start/references/manage-work-unit.md (where status is set to completed).\n- Add: manifest.cjs set {work_unit} completed_at {current_date_ISO}\n- The completed_at field is what compaction (Task 4-5) uses to calculate decay TTL. Without it, completed work units cannot expire and the index grows without bound.\n- This complements Task 5-2 which adds completed_at in processing skills and bridge continuations where completion happens automatically. The manage menu is where users manually mark work units as done — both paths must set the field.\n- Format: YYYY-MM-DD (ISO date, same as the migration backfill in Task 4-2).\n\nSUPERSESSION REMOVAL (specification process skill):\n- Find the specification process skill: skills/workflow-specification-process/SKILL.md\n- Locate the supersession action — where a spec's manifest status changes to superseded.\n- Add: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs remove --work-unit {work_unit} --phase specification --topic {topic}\n- This removes ONLY the superseded topic's spec chunks. Other topics in the same work unit (e.g., other specs in an epic) are unaffected. Granularity matters (design doc line 656).\n- The specification process skill already has allowed-tools for knowledge.cjs from Task 5-2 (for indexing). No additional frontmatter change needed.\n\nPROMOTION REMOVAL (specification process skill):\n- Locate the promotion action — where a spec's manifest status changes to promoted.\n- Add the same remove command: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs remove --work-unit {work_unit} --phase specification --topic {topic}\n- Promotion is a RELOCATION, not a deletion (design doc line 535). The chunks are removed from the original work unit. The new cross-cutting spec will be indexed naturally when it completes in the new work unit. There is a timing gap where the content is absent from the knowledge base — this is accepted per design doc line 537.\n- Research, discussion, and investigation chunks from the original work unit are KEPT — only the spec chunks are removed (design doc line 539).\n\nALLOWED-TOOLS SUMMARY FOR PHASE 5:\n- Task 5-1 adds to 11 entry-point skills (for check + compact). workflow-start is one of them, which covers the manage-work-unit.md reference file used by this task.\n- Task 5-2 adds to 5 indexed phase processing skills (for index), and updates bridge continuation files.\n- This task adds NO new allowed-tools entries — all target files are covered by Tasks 5-1 or 5-2.\n- Total Phase 5 allowed-tools changes: 16 skills (11 from 5-1 + 5 from 5-2).\n- The 3 non-indexed processing skills (planning, implementation, review) get allowed-tools in Phase 6 Task 6-2 when autonomous querying is added — no Phase 5 reason to add them now.\n- Phase entry skills (workflow-*-entry) do NOT get allowed-tools in Phase 5. The one exception is workflow-planning-entry, which gets allowed-tools in Phase 6 Task 6-3 specifically for the cross-cutting query. No other phase entry skill needs it.\n\nAcceptance Criteria:\n- Cancelling a work unit via manage menu removes its chunks from the knowledge base\n- Cancellation removal failure does not block the cancellation action\n- Manage menu done action sets completed_at on the work unit manifest\n- Superseding a spec removes only that topic's spec chunks\n- Promoting a spec removes only that topic's spec chunks from the original work unit\n- Research/discussion/investigation chunks from the same work unit survive supersession and promotion\n- No new allowed-tools frontmatter edits in this task (covered by Task 5-1 for workflow-start, Task 5-2 for specification-process)\n\nTests:\n- No automated tests — skill file editing task. Validation is manual:\n - Cancel a work unit that has indexed chunks -\u003e verify chunks are removed (knowledge status)\n - Mark a work unit as done via manage menu -\u003e verify completed_at is set in manifest\n - Supersede a spec topic in an epic -\u003e verify only that topic's spec chunks are removed, other topics and non-spec phases survive\n\nEdge Cases:\n- Cancellation of a work unit that was never indexed — knowledge remove returns 0 removed, no error. The cancellation flow should not treat this as a failure.\n- Supersession of a spec that was never indexed — same, 0 removed, no error.\n- Promotion timing gap — between removing original spec chunks and the new cross-cutting spec completing, the content is absent from the knowledge base. This is accepted per design doc.\n- Epic with multiple spec topics — superseding one MUST NOT remove others. The --topic flag ensures granularity.\n- Done action on a work unit that already has completed_at — overwrite with current date (the user is explicitly marking it done now, regardless of previous state).\n\nSpec Reference: knowledge-base/design.md — Work Unit Lifecycle section (lines 799-801, cancelled work units auto-removed, failure handling), Staleness and Supersession section (lines 530-539, superseded removed, promoted relocated, research/discussion/investigation kept), completed_at prerequisite (line 824, manage menu done action must set it), allowed-tools frontmatter changes (lines 728-733)","transitions":[{"from":"open","to":"in_progress","at":"2026-04-16T20:19:57Z","auto":false},{"from":"in_progress","to":"done","at":"2026-04-16T20:20:59Z","auto":false}],"parent":"tick-77697a","created":"2026-04-09T17:58:53Z","updated":"2026-04-16T20:20:59Z","closed":"2026-04-16T20:20:59Z"} {"id":"tick-496c59","title":"Phase 6: Retrieval Integration","status":"in_progress","priority":2,"refs":["knowledge-base-6"],"transitions":[{"from":"open","to":"in_progress","at":"2026-04-18T18:59:31Z","auto":true}],"parent":"tick-cbbd13","created":"2026-04-09T18:09:56Z","updated":"2026-04-18T18:59:31Z"} {"id":"tick-09d9ca","title":"Knowledge SKILL.md + Two-Step Retrieval Documentation","status":"done","priority":2,"type":"task","refs":["knowledge-base-6-1"],"description":"Problem: The knowledge base CLI exists (Phases 1-4) and is wired into skills (Phase 5), but Claude has no documentation explaining what it is, how to use it, or when to query it. Without Layer 1, Layers 2 and 3 have nothing to reference for API details.\n\nSolution: Create the knowledge skill file (SKILL.md) that serves as the API documentation layer — what commands exist, how to call them, what the output looks like, and how the two-step retrieval pattern works.\n\nOutcome: A comprehensive skill file that any processing skill can reference for knowledge base API details, enabling Claude to query the knowledge base correctly.\n\nDo:\n- Create skills/workflow-knowledge/SKILL.md following the project's skill file conventions (see CLAUDE.md Skill File Structure section).\n- This is a model-invocable skill, not user-invocable. It is loaded by reference from Layer 2 usage references (Task 6-2). It is NOT directly invoked by users.\n- Content sections:\n\n PURPOSE:\n - What the knowledge base is: a RAG system storing all workflow artifacts at full fidelity for semantic search\n - Why it exists: cross-work-unit and intra-work-unit context surfacing\n - What it indexes: research, discussion, investigation, specification (not planning, implementation, review)\n\n QUERY COMMAND:\n - Single query: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs query \u003csearch_term\u003e [flags]\n - Batch query: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs query \u003cterm1\u003e \u003cterm2\u003e [termN...] [flags]\n Multiple positional arguments run separate searches, merge results, deduplicate by chunk ID (highest score kept), apply --limit to merged set. Efficient: one store load, multiple searches.\n - Flags: --work-type, --phase, --work-unit (re-ranking hint, not filter), --limit\n - Search modes: hybrid (default when provider configured), keyword-only (when no provider)\n - Query construction guidance: use natural language, not topic slugs. Descriptive queries produce better semantic matching. Multiple queries from different angles are encouraged.\n - Example queries showing good vs poor query construction\n\n OUTPUT FORMAT:\n - Document the exact format (from design doc lines 580-603):\n [N results]\n [phase | work_unit/topic | confidence | YYYY-MM-DD]\n chunk content verbatim\n Source: source_file_path\n - Result count header, provenance line, verbatim content, source path\n - Empty results: [0 results]\n - Stub mode note when applicable: [keyword-only mode — configure embedding provider for semantic search]\n\n CONFIDENCE TIERS:\n - Explain what confidence means and how to weigh it:\n specification (high) — validated decisions, what was decided and why\n investigation (medium) — diagnostic knowledge, tied to specific symptoms\n discussion (low-medium) — conversational, may contain corrected assumptions\n research (low) — exploratory, may contain dead ends and rejected paths\n - Low confidence is not low value — research that rejected an approach prevents re-exploring dead ends\n\n TWO-STEP RETRIEVAL PATTERN:\n - Step 1: query returns chunks with provenance (lightweight, lands in context)\n - Step 2: if a chunk looks relevant, read the actual source file (source_file in metadata) for full detail\n - This keeps context lean — surface-level awareness, deep dive on demand\n - Claude should NOT read source files for every result, only when a chunk warrants deeper investigation\n\n WHAT NOT TO DO:\n - Do not dump large result sets into context speculatively\n - Do not query using topic slugs as search terms (poor semantic signal)\n - Do not query during specification phase (explicitly excluded — spec turns decisions into a golden doc, cross-cutting concerns merge at planning time)\n - Do not prepend metadata to stored content (already in enum fields)\n\nAcceptance Criteria:\n- SKILL.md exists at skills/workflow-knowledge/SKILL.md\n- Documents both single and batch query invocation forms\n- Documents all query flags and their behaviour\n- Documents the exact output format with examples\n- Documents confidence tiers with guidance on how to weigh them\n- Documents the two-step retrieval pattern (query -\u003e read source file on demand)\n- Documents what NOT to do (spec exclusion, slug queries, speculative dumps)\n- Follows project skill file conventions from CLAUDE.md\n- Can be loaded by reference from Layer 2 files (Task 6-2)\n\nTests:\n- No automated tests — documentation task. Validation is manual:\n - Read the SKILL.md and verify it provides enough information to correctly construct and interpret knowledge queries\n - Verify it follows the project's skill file structure conventions\n\nEdge Cases:\n- The SKILL.md must describe BOTH hybrid and keyword-only modes without making keyword-only feel broken — it is a supported degraded mode\n- Must not duplicate the CLI help text verbatim — this is higher-level guidance about when and why, not just how\n- Must explain that --work-unit is a re-ranking hint, not a filter — this is a common misunderstanding that would produce wrong queries if not clear\n- Batch query section must explain deduplication and merged limit behaviour\n\nSpec Reference: knowledge-base/design.md — Three-layer integration pattern (lines 716-724, Layer 1 description), Retrieved Context Format (lines 576-605, exact output format), Confidence Tiers (lines 514-525), Two-step retrieval pattern (lines 735-737), Query construction (line 737), Batch query (line 602-603, merged and deduplicated), Specification excluded from automatic retrieval (line 560)","transitions":[{"from":"open","to":"in_progress","at":"2026-04-18T18:59:31Z","auto":false},{"from":"in_progress","to":"done","at":"2026-04-18T19:01:08Z","auto":false}],"parent":"tick-496c59","created":"2026-04-09T18:22:30Z","updated":"2026-04-18T19:01:08Z","closed":"2026-04-18T19:01:08Z"} -{"id":"tick-c5a9f0","title":"Per-Phase Usage References + Contextual Query at Phase Start","status":"open","priority":2,"type":"task","refs":["knowledge-base-6-2"],"description":"Problem: Layer 1 (SKILL.md) documents the API, but Claude needs phase-specific guidance on WHEN to query and WHY — the trigger heuristics contextualised for each phase's work. Without Layer 2, Claude has the capability but not the judgment to use it effectively. Additionally, Claude needs explicit guidance on how to handle query failures — the design doc mandates pausing the workflow, not silently proceeding.\n\nSolution: Create usage reference files loaded early in processing skills that describe when and why to query during each specific phase, how to handle failures, plus the contextual query at phase start for research, discussion, and investigation.\n\nOutcome: Every processing skill loads phase-appropriate querying guidance early in its flow, the three early phases perform a contextual query at phase start, and query failures are handled by pausing with user options rather than silently skipping.\n\nDo:\n\nUSAGE REFERENCE FILES (Layer 2):\n- Create reference files — either one shared file or per-phase files, depending on how much the guidance differs between phases. The design doc (line 720) says: may be shared if guidance is generic enough, or local per phase if each needs different emphasis.\n- Recommended approach: one shared reference at skills/workflow-shared/references/knowledge-usage.md that covers the common trigger heuristics, with phase-specific notes where needed. This avoids maintaining 8 near-identical files.\n- Content:\n - Load the knowledge SKILL.md (Layer 1, Task 6-1) by reference for API details\n - Trigger heuristics — when to query (from design doc lines 551-557):\n 1. At topic boundaries — conversation edges toward adjacent territory\n 2. Upstream/downstream dependencies — current topic may affect or be affected by other work\n 3. Unfamiliar territory — not sure whether something was explored before\n 4. User prompts — user asks to check for prior context\n - Encourage proactive querying — under-querying is the bigger risk (design doc line 1003)\n - Multiple queries from different angles are expected and encouraged\n - Query construction: use natural language derived from what is currently being discussed, not topic names\n - Two-step retrieval reminder: query first (lightweight), read source file only when a chunk warrants investigation\n\nQUERY FAILURE HANDLING (from design doc lines 767-776):\n- This is skill-level behavior, not CLI behavior. The CLI retries 3 times and then exits with a non-zero code and error message (Task 4-4). The SKILL must handle what happens next:\n 1. If knowledge query fails (non-zero exit): PAUSE the workflow. Do not silently proceed without context.\n 2. Present the error clearly: what failed, likely causes (API key expired, network down, store corrupted).\n 3. Offer the user two options: fix the issue and retry, or explicitly choose to proceed without knowledge context.\n 4. If the user chooses to proceed: continue the phase but note that knowledge retrieval was skipped. This note should be visible in the output so the user knows context may be missing.\n- The design doc is emphatic: the value of the knowledge base is too high to silently skip (line 776).\n- This failure handling guidance goes in the usage reference (Layer 2) so it applies to all phases that load it.\n\n- Phase-specific notes within the shared reference (or in separate files if warranted):\n - Research: query at start + throughout. Early phase, high chance of overlap with prior work.\n - Discussion: query at start + throughout. Decisions being made that may relate to prior decisions.\n - Investigation: query at start + throughout. Symptoms and root causes may have been seen before.\n - Specification: EXCLUDED from automatic retrieval. Explicit note: do not query during spec authoring. Cross-cutting concerns merge at planning time, not spec time (design doc line 560).\n - Scoping: query throughout. Quick-fix scoping benefits from knowing if the issue was discussed elsewhere.\n - Planning: query throughout, especially for cross-cutting context. The explicit cross-cutting query is handled separately (Task 6-3).\n - Implementation: query when hitting unfamiliar territory or when a task touches areas covered by prior work.\n - Review: query to verify decisions against prior context.\n\nCONTEXTUAL QUERY AT PHASE START:\n- Add to the processing skills for research, discussion, and investigation: at the beginning of the phase (after loading references, before the first substantive step), construct a natural language query from available context and search the knowledge base.\n- Available context for query construction (from design doc line 549): topic description, bootstrap answers, handoff context, problem statement — whatever is available at that point.\n- NOT the topic slug. The query must be descriptive: not auth-flow but user authentication flow using OAuth2 with PKCE for mobile and web clients.\n- Returns a small, focused result set. Zero cost if nothing comes back. High value when it catches prior work.\n- This is a single query, not a dump. If results come back, Claude reads them and proceeds with that context. If nothing comes back, proceed as normal.\n- Specification is EXCLUDED — no contextual query at spec phase start.\n\nLOAD DIRECTIVES IN PROCESSING SKILLS:\n- Add a load directive for the usage reference early in each processing skill (alongside where case conventions are loaded). The exact insertion point varies per skill — read each to find the right place.\n- Processing skills that need this:\n skills/workflow-research-process/SKILL.md\n skills/workflow-discussion-process/SKILL.md\n skills/workflow-investigation-process/SKILL.md\n skills/workflow-scoping-process/SKILL.md\n skills/workflow-planning-process/SKILL.md\n skills/workflow-implementation-process/SKILL.md\n skills/workflow-review-process/SKILL.md\n- Specification process does NOT load the usage reference (excluded from automatic retrieval).\n\nALLOWED-TOOLS FOR REMAINING PROCESSING SKILLS:\n- Add Bash(node .claude/skills/workflow-knowledge/scripts/knowledge.cjs) to:\n skills/workflow-planning-process/SKILL.md\n skills/workflow-implementation-process/SKILL.md\n skills/workflow-review-process/SKILL.md\n- These 3 were deferred from Phase 5 — now they need it for autonomous querying.\n- Scoping process already has it from Phase 5 Task 5-2. Research, discussion, investigation, specification process already have it from Task 5-2.\n\nAcceptance Criteria:\n- Usage reference file(s) exist with trigger heuristics and phase-specific guidance\n- Usage reference loads Layer 1 (SKILL.md) by reference for API details\n- Query failure handling documented: pause workflow, present error, offer user choice to proceed or fix\n- All 7 processing skills (except specification) load the usage reference early in their flow\n- Specification process does NOT load the usage reference\n- Research, discussion, and investigation processing skills perform a contextual query at phase start\n- Contextual query uses descriptive natural language, not topic slugs\n- allowed-tools added to planning, implementation, and review processing skills\n- Trigger heuristics match the design doc (topic boundaries, dependencies, unfamiliar territory, user prompts)\n\nTests:\n- No automated tests — skill file editing task. Validation is manual:\n - Start a discussion in a test project with existing indexed knowledge -\u003e verify contextual query runs and surfaces relevant prior work\n - Start a specification -\u003e verify no contextual query runs\n - Simulate query failure -\u003e verify workflow pauses with user options (not silent skip)\n - Verify all processing skills load the usage reference\n\nEdge Cases:\n- Contextual query with no prior knowledge indexed — returns [0 results], phase proceeds normally with no delay or noise\n- Phase start with very little context available (e.g., just a topic name) — construct the best query possible from what is available. A poor query that returns nothing is fine. The design doc accepts zero cost if nothing comes back.\n- Query failure during contextual query at phase start — same failure handling applies (pause, present, offer choice). The contextual query is not exempt from failure handling.\n- Shared vs per-phase reference: if a shared reference becomes unwieldy with too many phase-specific notes, split into per-phase files. Start shared, split if needed.\n\nSpec Reference: knowledge-base/design.md — Three-layer integration pattern (lines 716-724, Layer 2 description), Autonomous querying trigger heuristics (lines 551-557), Contextual query at phase start (line 549), Specification excluded (line 560), Query Failures section (lines 767-776, pause workflow, present error, user choice), Autonomous query guardrails review finding #16 (line 1002)","parent":"tick-496c59","created":"2026-04-09T18:23:15Z","updated":"2026-04-09T18:30:02Z"} +{"id":"tick-c5a9f0","title":"Per-Phase Usage References + Contextual Query at Phase Start","status":"done","priority":2,"type":"task","refs":["knowledge-base-6-2"],"description":"Problem: Layer 1 (SKILL.md) documents the API, but Claude needs phase-specific guidance on WHEN to query and WHY — the trigger heuristics contextualised for each phase's work. Without Layer 2, Claude has the capability but not the judgment to use it effectively. Additionally, Claude needs explicit guidance on how to handle query failures — the design doc mandates pausing the workflow, not silently proceeding.\n\nSolution: Create usage reference files loaded early in processing skills that describe when and why to query during each specific phase, how to handle failures, plus the contextual query at phase start for research, discussion, and investigation.\n\nOutcome: Every processing skill loads phase-appropriate querying guidance early in its flow, the three early phases perform a contextual query at phase start, and query failures are handled by pausing with user options rather than silently skipping.\n\nDo:\n\nUSAGE REFERENCE FILES (Layer 2):\n- Create reference files — either one shared file or per-phase files, depending on how much the guidance differs between phases. The design doc (line 720) says: may be shared if guidance is generic enough, or local per phase if each needs different emphasis.\n- Recommended approach: one shared reference at skills/workflow-shared/references/knowledge-usage.md that covers the common trigger heuristics, with phase-specific notes where needed. This avoids maintaining 8 near-identical files.\n- Content:\n - Load the knowledge SKILL.md (Layer 1, Task 6-1) by reference for API details\n - Trigger heuristics — when to query (from design doc lines 551-557):\n 1. At topic boundaries — conversation edges toward adjacent territory\n 2. Upstream/downstream dependencies — current topic may affect or be affected by other work\n 3. Unfamiliar territory — not sure whether something was explored before\n 4. User prompts — user asks to check for prior context\n - Encourage proactive querying — under-querying is the bigger risk (design doc line 1003)\n - Multiple queries from different angles are expected and encouraged\n - Query construction: use natural language derived from what is currently being discussed, not topic names\n - Two-step retrieval reminder: query first (lightweight), read source file only when a chunk warrants investigation\n\nQUERY FAILURE HANDLING (from design doc lines 767-776):\n- This is skill-level behavior, not CLI behavior. The CLI retries 3 times and then exits with a non-zero code and error message (Task 4-4). The SKILL must handle what happens next:\n 1. If knowledge query fails (non-zero exit): PAUSE the workflow. Do not silently proceed without context.\n 2. Present the error clearly: what failed, likely causes (API key expired, network down, store corrupted).\n 3. Offer the user two options: fix the issue and retry, or explicitly choose to proceed without knowledge context.\n 4. If the user chooses to proceed: continue the phase but note that knowledge retrieval was skipped. This note should be visible in the output so the user knows context may be missing.\n- The design doc is emphatic: the value of the knowledge base is too high to silently skip (line 776).\n- This failure handling guidance goes in the usage reference (Layer 2) so it applies to all phases that load it.\n\n- Phase-specific notes within the shared reference (or in separate files if warranted):\n - Research: query at start + throughout. Early phase, high chance of overlap with prior work.\n - Discussion: query at start + throughout. Decisions being made that may relate to prior decisions.\n - Investigation: query at start + throughout. Symptoms and root causes may have been seen before.\n - Specification: EXCLUDED from automatic retrieval. Explicit note: do not query during spec authoring. Cross-cutting concerns merge at planning time, not spec time (design doc line 560).\n - Scoping: query throughout. Quick-fix scoping benefits from knowing if the issue was discussed elsewhere.\n - Planning: query throughout, especially for cross-cutting context. The explicit cross-cutting query is handled separately (Task 6-3).\n - Implementation: query when hitting unfamiliar territory or when a task touches areas covered by prior work.\n - Review: query to verify decisions against prior context.\n\nCONTEXTUAL QUERY AT PHASE START:\n- Add to the processing skills for research, discussion, and investigation: at the beginning of the phase (after loading references, before the first substantive step), construct a natural language query from available context and search the knowledge base.\n- Available context for query construction (from design doc line 549): topic description, bootstrap answers, handoff context, problem statement — whatever is available at that point.\n- NOT the topic slug. The query must be descriptive: not auth-flow but user authentication flow using OAuth2 with PKCE for mobile and web clients.\n- Returns a small, focused result set. Zero cost if nothing comes back. High value when it catches prior work.\n- This is a single query, not a dump. If results come back, Claude reads them and proceeds with that context. If nothing comes back, proceed as normal.\n- Specification is EXCLUDED — no contextual query at spec phase start.\n\nLOAD DIRECTIVES IN PROCESSING SKILLS:\n- Add a load directive for the usage reference early in each processing skill (alongside where case conventions are loaded). The exact insertion point varies per skill — read each to find the right place.\n- Processing skills that need this:\n skills/workflow-research-process/SKILL.md\n skills/workflow-discussion-process/SKILL.md\n skills/workflow-investigation-process/SKILL.md\n skills/workflow-scoping-process/SKILL.md\n skills/workflow-planning-process/SKILL.md\n skills/workflow-implementation-process/SKILL.md\n skills/workflow-review-process/SKILL.md\n- Specification process does NOT load the usage reference (excluded from automatic retrieval).\n\nALLOWED-TOOLS FOR REMAINING PROCESSING SKILLS:\n- Add Bash(node .claude/skills/workflow-knowledge/scripts/knowledge.cjs) to:\n skills/workflow-planning-process/SKILL.md\n skills/workflow-implementation-process/SKILL.md\n skills/workflow-review-process/SKILL.md\n- These 3 were deferred from Phase 5 — now they need it for autonomous querying.\n- Scoping process already has it from Phase 5 Task 5-2. Research, discussion, investigation, specification process already have it from Task 5-2.\n\nAcceptance Criteria:\n- Usage reference file(s) exist with trigger heuristics and phase-specific guidance\n- Usage reference loads Layer 1 (SKILL.md) by reference for API details\n- Query failure handling documented: pause workflow, present error, offer user choice to proceed or fix\n- All 7 processing skills (except specification) load the usage reference early in their flow\n- Specification process does NOT load the usage reference\n- Research, discussion, and investigation processing skills perform a contextual query at phase start\n- Contextual query uses descriptive natural language, not topic slugs\n- allowed-tools added to planning, implementation, and review processing skills\n- Trigger heuristics match the design doc (topic boundaries, dependencies, unfamiliar territory, user prompts)\n\nTests:\n- No automated tests — skill file editing task. Validation is manual:\n - Start a discussion in a test project with existing indexed knowledge -\u003e verify contextual query runs and surfaces relevant prior work\n - Start a specification -\u003e verify no contextual query runs\n - Simulate query failure -\u003e verify workflow pauses with user options (not silent skip)\n - Verify all processing skills load the usage reference\n\nEdge Cases:\n- Contextual query with no prior knowledge indexed — returns [0 results], phase proceeds normally with no delay or noise\n- Phase start with very little context available (e.g., just a topic name) — construct the best query possible from what is available. A poor query that returns nothing is fine. The design doc accepts zero cost if nothing comes back.\n- Query failure during contextual query at phase start — same failure handling applies (pause, present, offer choice). The contextual query is not exempt from failure handling.\n- Shared vs per-phase reference: if a shared reference becomes unwieldy with too many phase-specific notes, split into per-phase files. Start shared, split if needed.\n\nSpec Reference: knowledge-base/design.md — Three-layer integration pattern (lines 716-724, Layer 2 description), Autonomous querying trigger heuristics (lines 551-557), Contextual query at phase start (line 549), Specification excluded (line 560), Query Failures section (lines 767-776, pause workflow, present error, user choice), Autonomous query guardrails review finding #16 (line 1002)","transitions":[{"from":"open","to":"in_progress","at":"2026-04-18T19:01:23Z","auto":false},{"from":"in_progress","to":"done","at":"2026-04-18T19:10:11Z","auto":false}],"parent":"tick-496c59","created":"2026-04-09T18:23:15Z","updated":"2026-04-18T19:10:11Z","closed":"2026-04-18T19:10:11Z"} {"id":"tick-2841d6","title":"Inline Callouts + Planning Entry Cross-Cutting Query","status":"open","priority":2,"type":"task","refs":["knowledge-base-6-3"],"description":"Problem: Layer 2 provides general guidance loaded once at the start of a phase, but Claude can lose awareness of the knowledge base as a conversation develops. Layer 3 addresses this with targeted nudges at specific moments where querying is most valuable. Additionally, the planning entry skill has an existing manual approach for cross-cutting context that should be replaced with a targeted semantic query.\n\nSolution: Add inline callouts at pertinent points in processing skills and replace the planning entry cross-cutting context approach with a knowledge base query.\n\nOutcome: Claude gets timely reminders to check the knowledge base at high-value moments, and planning entry uses semantic search instead of manually reading every cross-cutting spec.\n\nDo:\n\nINLINE CALLOUTS (Layer 3):\n- Add brief reminders within the step flow of processing skills at moments where the knowledge base is most valuable. These are nudges, not full reference loads — same pattern as existing callouts for review agents and commit reminders (design doc line 722).\n- Format: a short inline note like: Consider querying the knowledge base — this subtopic may have been explored in prior work. Or: If this constraint seems familiar, check the knowledge base for prior decisions.\n- Placement is judgment-based — read each processing skill and identify moments where:\n - A complex subtopic is being explored\n - A decision is being made that could conflict with prior work\n - An assumption is being introduced that may have been validated or rejected before\n - The conversation moves to adjacent territory\n- Processing skills to add callouts to (all except specification):\n skills/workflow-research-process/SKILL.md — when exploring new directions, before concluding\n skills/workflow-discussion-process/SKILL.md — when discussing options, before deciding\n skills/workflow-investigation-process/SKILL.md — when analysing root causes\n skills/workflow-scoping-process/SKILL.md — when scoping constraints\n skills/workflow-planning-process/SKILL.md — when designing phases/tasks that touch other areas\n skills/workflow-implementation-process/SKILL.md — when hitting unfamiliar code areas\n skills/workflow-review-process/SKILL.md — when verifying decisions against original intent\n- These are 1-2 line callouts embedded at specific step boundaries, NOT new steps or reference loads. They should feel natural, not interruptive.\n- Do NOT add callouts to the specification process — specification is excluded from automatic retrieval.\n\nPLANNING ENTRY CROSS-CUTTING QUERY:\n- This replaces existing functionality in skills/workflow-planning-entry/references/cross-cutting-context.md (design doc line 562).\n- The current approach: reads every cross-cutting specification and manually assesses relevance to the current topic. This is expensive (loads all cross-cutting specs into context) and keyword-dependent (misses semantic connections).\n- The replacement: a targeted semantic query filtered to work_type: cross-cutting.\n node .claude/skills/workflow-knowledge/scripts/knowledge.cjs query \u003ctopic_description\u003e --work-type cross-cutting --limit 10\n- The query term should be constructed from the current topic's specification summary or description — not the topic name.\n- Results are cross-cutting specs that are semantically relevant to the current plan. Claude reads the results, identifies applicable cross-cutting decisions, and incorporates them into the planning context.\n- This is a deterministic step replacing existing functionality, not a speculative search (design doc line 726).\n- Update or replace cross-cutting-context.md to use the knowledge query instead of manual spec reading.\n- Ensure skills/workflow-planning-entry/SKILL.md has allowed-tools for knowledge.cjs if not already present (it may have been added as an entry-point skill in Task 5-1, but planning-entry is a phase entry skill, not an entry-point skill — check).\n\nAcceptance Criteria:\n- Inline callouts exist at pertinent points in 7 processing skills (all except specification)\n- Callouts are brief nudges (1-2 lines), not full reference loads\n- Callouts are placed at high-value moments identified by reading each skill's flow\n- Specification process has NO callouts\n- Planning entry cross-cutting query replaces the manual approach in cross-cutting-context.md\n- Cross-cutting query uses --work-type cross-cutting filter\n- Cross-cutting query uses descriptive topic text, not topic slug\n- Planning entry has allowed-tools for knowledge.cjs\n\nTests:\n- No automated tests — skill file editing task. Validation is manual:\n - Read processing skills and verify callouts are placed at high-value moments\n - Start planning for a topic with existing cross-cutting specs indexed -\u003e verify the query surfaces relevant cross-cutting decisions\n - Verify the old manual cross-cutting spec reading approach is replaced, not duplicated\n\nEdge Cases:\n- Planning entry cross-cutting query when no cross-cutting specs are indexed — returns [0 results], planning proceeds without cross-cutting context (same as today when no cross-cutting specs exist)\n- Callout placement in skills with varying step structures — read each skill carefully, do not add callouts at the same structural position in every skill. Placement is semantic, not mechanical.\n- The planning-entry skill is a phase entry skill (internal, user-invocable: false), not an entry-point skill. It was NOT updated in Task 5-1 (which targeted start-*/continue-* skills). It needs allowed-tools for the cross-cutting query added here.\n\nSpec Reference: knowledge-base/design.md — Three-layer integration pattern (lines 716-724, Layer 3 description — inline callouts same pattern as review agents and commit reminders), Planning entry cross-cutting query (line 562, replaces existing manual approach, filtered to work_type: cross-cutting), and the note that this is a deterministic step replacing existing functionality (line 726)","parent":"tick-496c59","created":"2026-04-09T18:23:50Z","updated":"2026-04-09T18:23:50Z"} {"id":"tick-2e511f","title":"Phase 7: Setup Wizard","status":"open","priority":2,"refs":["knowledge-base-7"],"parent":"tick-cbbd13","created":"2026-04-09T19:04:09Z","updated":"2026-04-09T19:04:09Z"} {"id":"tick-78c1c7","title":"Setup Wizard: System Config + Project Init + Stub Mode","status":"open","priority":2,"type":"task","refs":["knowledge-base-7-1"],"description":"Problem: Users need a single entry point to configure the knowledge base for the first time. This involves system-level configuration (API keys, provider choice) that lives in the user's home directory and project-level initialisation that lives in .workflows/. Both must be handled in one flow so the user doesn't need to know the internal structure.\n\nSolution: Implement the knowledge setup command as an interactive wizard using Node's readline interface, handling system config, project init, and stub mode in one guided flow.\n\nOutcome: A user can run one command and have a fully configured knowledge base ready for use, with clear prompts at each step and graceful handling of partial or existing configuration.\n\nDo:\n- Implement the setup command handler in the CLI (invoked by Task 3-1 dispatch).\n- Invocation: knowledge setup (no arguments)\n- HUMAN-ONLY — uses interactive prompts throughout via Node readline interface (process.stdin/process.stdout). Claude cannot handle interactive terminals — this is the natural protection against accidental invocation (design doc line 632).\n\nSTEP 1: SYSTEM CONFIG (~/.config/workflows/config.json):\n- Check if system config already exists.\n - If it exists: read it, display current settings, ask if the user wants to reconfigure or skip. If skip, proceed to Step 2.\n - If it does not exist: create ~/.config/workflows/ directory if needed.\n- Prompt for provider:\n Which embedding provider? (openai / skip)\n - openai: proceed with OpenAI configuration\n - skip: stub mode (keyword-only search, no embeddings). Write config with no provider field. Display clear message about limitations. Proceed to Step 2.\n- If openai selected:\n - Prompt for model (default: text-embedding-3-small):\n Embedding model [text-embedding-3-small]:\n - Prompt for dimensions (default: 1536):\n Vector dimensions [1536]:\n - Prompt for API key env var name (default: OPENAI_API_KEY):\n API key environment variable [OPENAI_API_KEY]:\n - Check if the env var is set in the current environment:\n - If set: validate with a test embed call — embed a short test string and verify a vector is returned. If validation fails, display the error and ask the user to fix it or continue anyway.\n - If not set: warn the user and explain they need to set this env var in their shell profile before using the knowledge base. Do not block — they may be setting it up for later.\n- Write system config to ~/.config/workflows/config.json:\n { knowledge: { provider, model, dimensions, api_key_env, similarity_threshold: 0.8, decay_months: 6 } }\n- For stub mode (skip): write minimal config:\n { knowledge: { similarity_threshold: 0.8, decay_months: 6 } }\n\nSTEP 2: PROJECT INIT (.workflows/.knowledge/):\n- Check if project knowledge base directory already exists with config.json and store.msp.\n - If fully initialised: display status and ask to skip or reinitialise. If skip, proceed to Step 3.\n - If partially initialised (directory exists but missing files): complete the missing pieces.\n - If not initialised: create from scratch.\n- Create .workflows/.knowledge/ directory.\n- Write .workflows/.knowledge/config.json — project-level config. By default this is empty (inherits everything from system config):\n { knowledge: {} }\n The user can customise project-level overrides later by editing this file.\n- Create an empty Orama store and save it to .workflows/.knowledge/store.msp using createStore + saveStore from Phase 1. Use the dimensions from the resolved config (system + project merge).\n- Write .workflows/.knowledge/metadata.json with the provider/model/dimensions from the resolved config (or empty provider fields for stub mode).\n\nREADLINE INTERFACE:\n- Use Node built-in readline module (require('readline')).\n- Create interface with input: process.stdin, output: process.stdout.\n- Use rl.question() for prompts with defaults shown in brackets.\n- Close the interface when done.\n- If stdin is not a TTY (piped input, non-interactive environment): detect with process.stdin.isTTY and abort with message: knowledge setup requires an interactive terminal. Run it directly, not through Claude.\n\nAcceptance Criteria:\n- knowledge setup prompts for provider, model, dimensions, API key env var\n- System config is written to ~/.config/workflows/config.json\n- Project knowledge base is initialised at .workflows/.knowledge/ with config.json, store.msp, metadata.json\n- Test embed call validates the API key when configured\n- Stub mode writes config without provider, displays limitation message\n- Existing system config is detected and can be skipped or reconfigured\n- Existing project init is detected and can be skipped\n- Non-interactive terminal is detected and aborts with clear message\n- npm run build succeeds with the setup command included\n\nTests:\n- No automated tests for the interactive flow — it is inherently human-driven.\n- Unit tests for the non-interactive parts (tests/scripts/test-knowledge-config.cjs — extend from Task 3-1):\n - it creates a valid system config object from provider choices\n - it creates a valid stub-mode config object\n - it detects existing system config correctly\n - it detects existing project init correctly\n - it creates the project directory structure correctly\n\nEdge Cases:\n- ~/.config/workflows/ directory does not exist — create it (mkdir -p equivalent with { recursive: true })\n- .workflows/ directory does not exist — this means no workflow project exists. Display error: No .workflows/ directory found. Initialise a workflow project first.\n- System config file exists but is invalid JSON — display error, offer to overwrite\n- API key env var is set but the test embed call fails (wrong key, network error) — display error, offer to continue setup anyway (user may fix the key later)\n- User presses Ctrl+C during setup — readline handles SIGINT, process exits cleanly\n- Previous setup was stub mode, user re-runs with openai — detect existing store has no vectors, suggest knowledge rebuild after setup completes\n\nSpec Reference: knowledge-base/design.md — knowledge setup command (lines 626-633, interactive wizard flow, skip logic, stub mode), System config creation flow review finding #18 (line 1008), Configuration Hierarchy section (lines 258-301, system and project config schemas)","parent":"tick-2e511f","created":"2026-04-09T19:05:02Z","updated":"2026-04-09T19:05:02Z"} diff --git a/skills/workflow-discussion-process/SKILL.md b/skills/workflow-discussion-process/SKILL.md index d3f44cf3..c5316ad4 100644 --- a/skills/workflow-discussion-process/SKILL.md +++ b/skills/workflow-discussion-process/SKILL.md @@ -126,7 +126,49 @@ Load **[discussion-guidelines.md](references/discussion-guidelines.md)** and fol --- -## Step 3: Discussion Session +## Step 3: Knowledge Usage + +> *Output the next fenced block as a code block:* + +``` +── Knowledge Usage ────────────────────────────── +``` + +> *Output the next fenced block as markdown (not a code block):* + +``` +> Loading the usage guide for the knowledge base so +> proactive querying is available throughout the discussion. +``` + +Load **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)** and follow its instructions as written. + +→ Proceed to **Step 4**. + +--- + +## Step 4: Contextual Query + +> *Output the next fenced block as a code block:* + +``` +── Contextual Query ───────────────────────────── +``` + +> *Output the next fenced block as markdown (not a code block):* + +``` +> Checking the knowledge base for prior work that relates +> to this discussion topic before the session begins. +``` + +Load **[contextual-query.md](../workflow-shared/references/contextual-query.md)** and follow its instructions as written. + +→ Proceed to **Step 5**. + +--- + +## Step 5: Discussion Session > *Output the next fenced block as a code block:* @@ -144,11 +186,11 @@ Load **[discussion-guidelines.md](references/discussion-guidelines.md)** and fol Load **[discussion-session.md](references/discussion-session.md)** and follow its instructions as written. -→ Proceed to **Step 4**. +→ Proceed to **Step 6**. --- -## Step 4: Final Gap Review +## Step 6: Final Gap Review > *Output the next fenced block as a code block:* @@ -165,11 +207,11 @@ Load **[discussion-session.md](references/discussion-session.md)** and follow it Load **[final-review.md](references/final-review.md)** and follow its instructions as written. -→ Proceed to **Step 5**. +→ Proceed to **Step 7**. --- -## Step 5: Document Review +## Step 7: Document Review > *Output the next fenced block as a code block:* @@ -186,11 +228,11 @@ Load **[final-review.md](references/final-review.md)** and follow its instructio Load **[document-review.md](references/document-review.md)** and follow its instructions as written. -→ Proceed to **Step 6**. +→ Proceed to **Step 8**. --- -## Step 6: Compliance Self-Check +## Step 8: Compliance Self-Check > *Output the next fenced block as a code block:* @@ -206,11 +248,11 @@ Load **[document-review.md](references/document-review.md)** and follow its inst Load **[compliance-check.md](../workflow-shared/references/compliance-check.md)** and follow its instructions as written. -→ Proceed to **Step 7**. +→ Proceed to **Step 9**. --- -## Step 7: Conclude Discussion +## Step 9: Conclude Discussion > *Output the next fenced block as a code block:* diff --git a/skills/workflow-discussion-process/references/conclude-discussion.md b/skills/workflow-discussion-process/references/conclude-discussion.md index 18f55bc3..811a302d 100644 --- a/skills/workflow-discussion-process/references/conclude-discussion.md +++ b/skills/workflow-discussion-process/references/conclude-discussion.md @@ -63,4 +63,4 @@ Invoke the workflow-bridge skill to enter plan mode with continuation instructio #### If `no` -→ Return to **[the skill](../SKILL.md)** for **Step 3**. +→ Return to **[the skill](../SKILL.md)** for **Step 5**. diff --git a/skills/workflow-discussion-process/references/final-review.md b/skills/workflow-discussion-process/references/final-review.md index c9af50d9..9ca7f35b 100644 --- a/skills/workflow-discussion-process/references/final-review.md +++ b/skills/workflow-discussion-process/references/final-review.md @@ -6,7 +6,7 @@ A final review ensures the discussion is thorough before moving to specification. Even if review agents ran during the session, the discussion may have progressed significantly since the last one. -This step runs once per "user signals done" entry. It dispatches a fresh review if needed, raises one finding via the shared protocol, then bounces back to the discussion session so the user can engage naturally. The next time the user signals done, Step 4 re-runs — eventually all findings are drained and the file transitions to `incorporated`, at which point Step 4 returns to the backbone to proceed toward conclusion. +This step runs once per "user signals done" entry. It dispatches a fresh review if needed, raises one finding via the shared protocol, then bounces back to the discussion session so the user can engage naturally. The next time the user signals done, Step 6 re-runs — eventually all findings are drained and the file transitions to `incorporated`, at which point Step 6 returns to the backbone to proceed toward conclusion. The **never-dump rules apply in full**. Findings are raised one at a time via the shared surfacing protocol. @@ -116,6 +116,6 @@ All findings have been raised (or the review came back with zero gaps). The fina #### If `status: acknowledged` -Either a finding was just raised, or the announce menu was just shown and the user picked `later`. Control belongs to the conversation — return the user to the discussion session so they can engage naturally. The session loop's check-for-results will pick up subsequent findings at natural breaks. When the user signals done again, Step 4 re-runs and this flow resumes. +Either a finding was just raised, or the announce menu was just shown and the user picked `later`. Control belongs to the conversation — return the user to the discussion session so they can engage naturally. The session loop's check-for-results will pick up subsequent findings at natural breaks. When the user signals done again, Step 6 re-runs and this flow resumes. -→ Return to **[the skill](../SKILL.md)** for **Step 3**. +→ Return to **[the skill](../SKILL.md)** for **Step 5**. diff --git a/skills/workflow-implementation-process/SKILL.md b/skills/workflow-implementation-process/SKILL.md index c008e0c2..7e350945 100644 --- a/skills/workflow-implementation-process/SKILL.md +++ b/skills/workflow-implementation-process/SKILL.md @@ -1,7 +1,7 @@ --- name: workflow-implementation-process user-invocable: false -allowed-tools: Bash(node .claude/skills/workflow-manifest/scripts/manifest.cjs) +allowed-tools: Bash(node .claude/skills/workflow-manifest/scripts/manifest.cjs), Bash(node .claude/skills/workflow-knowledge/scripts/knowledge.cjs) --- # Implementation Process @@ -195,7 +195,28 @@ Load **[linter-setup.md](references/linter-setup.md)** and follow its instructio --- -## Step 6: Task Loop +## Step 6: Knowledge Usage + +> *Output the next fenced block as a code block:* + +``` +── Knowledge Usage ────────────────────────────── +``` + +> *Output the next fenced block as markdown (not a code block):* + +``` +> Loading the usage guide for the knowledge base so +> proactive querying is available while tasks execute. +``` + +Load **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)** and follow its instructions as written. + +→ Proceed to **Step 7**. + +--- + +## Step 7: Task Loop > *Output the next fenced block as a code block:* @@ -217,17 +238,17 @@ After the loop completes: #### If the task loop exited early (user chose `stop`) -→ Proceed to **Step 8**. +→ Proceed to **Step 9**. #### Otherwise -**CRITICAL**: This routing applies on **every** task loop completion — including after returning from Step 7 with analysis-created tasks. Step 6 and Step 7 form a mandatory cycle: tasks execute → analysis runs → new tasks may be created → tasks execute again → analysis runs again. Never skip Step 7 after a task loop completes. +**CRITICAL**: This routing applies on **every** task loop completion — including after returning from Step 8 with analysis-created tasks. Step 7 and Step 8 form a mandatory cycle: tasks execute → analysis runs → new tasks may be created → tasks execute again → analysis runs again. Never skip Step 8 after a task loop completes. -→ Proceed to **Step 7**. +→ Proceed to **Step 8**. --- -## Step 7: Analysis Loop +## Step 8: Analysis Loop > *Output the next fenced block as a code block:* @@ -247,15 +268,15 @@ Load **[analysis-loop.md](references/analysis-loop.md)** and follow its instruct #### If new tasks were created in the plan -→ Return to **Step 6**. +→ Return to **Step 7**. #### If no tasks were created -→ Proceed to **Step 8**. +→ Proceed to **Step 9**. --- -## Step 8: Compliance Self-Check +## Step 9: Compliance Self-Check > *Output the next fenced block as a code block:* @@ -271,11 +292,11 @@ Load **[analysis-loop.md](references/analysis-loop.md)** and follow its instruct Load **[compliance-check.md](../workflow-shared/references/compliance-check.md)** and follow its instructions as written. -→ Proceed to **Step 9**. +→ Proceed to **Step 10**. --- -## Step 9: Mark Implementation Complete +## Step 10: Mark Implementation Complete > *Output the next fenced block as a code block:* diff --git a/skills/workflow-implementation-process/references/analysis-loop.md b/skills/workflow-implementation-process/references/analysis-loop.md index b6265979..9ad40a44 100644 --- a/skills/workflow-implementation-process/references/analysis-loop.md +++ b/skills/workflow-implementation-process/references/analysis-loop.md @@ -55,7 +55,7 @@ You MUST NOT choose on the user's behalf. **If `skip`:** -→ Return to **[the skill](../SKILL.md)** for **Step 8**. +→ Return to **[the skill](../SKILL.md)** for **Step 9**. --- @@ -139,7 +139,7 @@ impl({work_unit}): analysis cycle {N} — findings #### If all three agents returned `STATUS: clean` -→ Return to **[the skill](../SKILL.md)** for **Step 8**. +→ Return to **[the skill](../SKILL.md)** for **Step 9**. #### Otherwise @@ -161,7 +161,7 @@ impl({work_unit}): analysis cycle {N} — synthesis #### If `STATUS` is `clean` -→ Return to **[the skill](../SKILL.md)** for **Step 8**. +→ Return to **[the skill](../SKILL.md)** for **Step 9**. #### If `STATUS` is `tasks_proposed` @@ -289,7 +289,7 @@ Commit the staging file updates: impl({work_unit}): analysis cycle {N} — tasks skipped ``` -→ Return to **[the skill](../SKILL.md)** for **Step 8**. +→ Return to **[the skill](../SKILL.md)** for **Step 9**. --- diff --git a/skills/workflow-implementation-process/references/conclude-implementation.md b/skills/workflow-implementation-process/references/conclude-implementation.md index 7d72fa73..f20d41e4 100644 --- a/skills/workflow-implementation-process/references/conclude-implementation.md +++ b/skills/workflow-implementation-process/references/conclude-implementation.md @@ -19,7 +19,7 @@ Ready to mark implementation as completed? #### If `no` -→ Return to **[the skill](../SKILL.md)** for **Step 6**. +→ Return to **[the skill](../SKILL.md)** for **Step 7**. #### If `yes` diff --git a/skills/workflow-implementation-process/references/task-loop.md b/skills/workflow-implementation-process/references/task-loop.md index 32e3abe8..c9c5562f 100644 --- a/skills/workflow-implementation-process/references/task-loop.md +++ b/skills/workflow-implementation-process/references/task-loop.md @@ -94,7 +94,7 @@ Task failed. How would you like to proceed? #### If `stop` -→ Return to **[the skill](../SKILL.md)** for **Step 8**. +→ Return to **[the skill](../SKILL.md)** for **Step 9**. --- diff --git a/skills/workflow-investigation-process/SKILL.md b/skills/workflow-investigation-process/SKILL.md index e25f153a..582ef29f 100644 --- a/skills/workflow-investigation-process/SKILL.md +++ b/skills/workflow-investigation-process/SKILL.md @@ -128,7 +128,28 @@ Load **[initialize-investigation.md](references/initialize-investigation.md)** a --- -## Step 2: Symptom Gathering +## Step 2: Knowledge Usage + +> *Output the next fenced block as a code block:* + +``` +── Knowledge Usage ────────────────────────────── +``` + +> *Output the next fenced block as markdown (not a code block):* + +``` +> Loading the usage guide for the knowledge base so +> proactive querying is available throughout the investigation. +``` + +Load **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)** and follow its instructions as written. + +→ Proceed to **Step 3**. + +--- + +## Step 3: Symptom Gathering > *Output the next fenced block as a code block:* @@ -149,11 +170,32 @@ Document symptoms in the investigation file as you gather them. Commit after eac When symptoms are sufficiently understood to begin code analysis: -→ Proceed to **Step 3**. +→ Proceed to **Step 4**. + +--- + +## Step 4: Contextual Query + +> *Output the next fenced block as a code block:* + +``` +── Contextual Query ───────────────────────────── +``` + +> *Output the next fenced block as markdown (not a code block):* + +``` +> Checking the knowledge base for prior investigations or +> related work that matches the symptoms just gathered. +``` + +Load **[contextual-query.md](../workflow-shared/references/contextual-query.md)** and follow its instructions as written. + +→ Proceed to **Step 5**. --- -## Step 3: Code Analysis +## Step 5: Code Analysis > *Output the next fenced block as a code block:* @@ -172,11 +214,11 @@ Load **[analysis-patterns.md](references/analysis-patterns.md)** and use its tec Document findings in the investigation file as you analyze. Commit after each significant finding. -→ Proceed to **Step 4**. +→ Proceed to **Step 6**. --- -## Step 4: Root Cause Synthesis +## Step 6: Root Cause Synthesis > *Output the next fenced block as a code block:* @@ -200,11 +242,11 @@ Synthesize findings into a clear root cause: Document in the investigation file and commit. -→ Proceed to **Step 5**. +→ Proceed to **Step 7**. --- -## Step 5: Root Cause Validation +## Step 7: Root Cause Validation > *Output the next fenced block as a code block:* @@ -221,11 +263,11 @@ Document in the investigation file and commit. Load **[synthesis-agent.md](references/synthesis-agent.md)** and follow its instructions as written. -→ Proceed to **Step 6**. +→ Proceed to **Step 8**. --- -## Step 6: Findings Review & Fix Discussion +## Step 8: Findings Review & Fix Discussion > *Output the next fenced block as a code block:* @@ -242,11 +284,11 @@ Load **[synthesis-agent.md](references/synthesis-agent.md)** and follow its inst Load **[findings-review.md](references/findings-review.md)** and follow its instructions as written. -→ Proceed to **Step 7**. +→ Proceed to **Step 9**. --- -## Step 7: Compliance Self-Check +## Step 9: Compliance Self-Check > *Output the next fenced block as a code block:* @@ -262,11 +304,11 @@ Load **[findings-review.md](references/findings-review.md)** and follow its inst Load **[compliance-check.md](../workflow-shared/references/compliance-check.md)** and follow its instructions as written. -→ Proceed to **Step 8**. +→ Proceed to **Step 10**. --- -## Step 8: Conclude Investigation +## Step 10: Conclude Investigation > *Output the next fenced block as a code block:* diff --git a/skills/workflow-investigation-process/references/conclude-investigation.md b/skills/workflow-investigation-process/references/conclude-investigation.md index 353d50a0..96e73111 100644 --- a/skills/workflow-investigation-process/references/conclude-investigation.md +++ b/skills/workflow-investigation-process/references/conclude-investigation.md @@ -21,7 +21,7 @@ Investigation complete. Ready to conclude? #### If keep going -→ Return to **[the skill](../SKILL.md)** for **Step 3**. +→ Return to **[the skill](../SKILL.md)** for **Step 5**. #### If `yes` diff --git a/skills/workflow-investigation-process/references/synthesis-agent.md b/skills/workflow-investigation-process/references/synthesis-agent.md index 547ccb5f..a2208550 100644 --- a/skills/workflow-investigation-process/references/synthesis-agent.md +++ b/skills/workflow-investigation-process/references/synthesis-agent.md @@ -119,6 +119,6 @@ Synthesis: {CONFIDENCE} confidence. {GAPS_COUNT} gap(s) identified. Full analysis: .workflows/.cache/{work_unit}/investigation/{topic}/synthesis-{NNN}.md ``` -Carry the synthesis context forward — Step 6 (Findings Review) will incorporate these gaps into the findings presentation. +Carry the synthesis context forward — Step 8 (Findings Review) will incorporate these gaps into the findings presentation. → Return to caller. diff --git a/skills/workflow-planning-process/SKILL.md b/skills/workflow-planning-process/SKILL.md index 3acf8b6f..433f1bea 100644 --- a/skills/workflow-planning-process/SKILL.md +++ b/skills/workflow-planning-process/SKILL.md @@ -1,7 +1,7 @@ --- name: workflow-planning-process user-invocable: false -allowed-tools: Bash(node .claude/skills/workflow-manifest/scripts/manifest.cjs) +allowed-tools: Bash(node .claude/skills/workflow-manifest/scripts/manifest.cjs), Bash(node .claude/skills/workflow-knowledge/scripts/knowledge.cjs) --- # Planning Process @@ -204,7 +204,28 @@ Load **[planning-principles.md](references/planning-principles.md)** and follow --- -## Step 4: Verify Source Material +## Step 4: Knowledge Usage + +> *Output the next fenced block as a code block:* + +``` +── Knowledge Usage ────────────────────────────── +``` + +> *Output the next fenced block as markdown (not a code block):* + +``` +> Loading the usage guide for the knowledge base so +> proactive querying is available while planning tasks. +``` + +Load **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)** and follow its instructions as written. + +→ Proceed to **Step 5**. + +--- + +## Step 5: Verify Source Material > *Output the next fenced block as a code block:* @@ -221,11 +242,11 @@ Load **[planning-principles.md](references/planning-principles.md)** and follow Load **[verify-source-material.md](references/verify-source-material.md)** and follow its instructions as written. -→ Proceed to **Step 5**. +→ Proceed to **Step 6**. --- -## Step 5: Plan Construction +## Step 6: Plan Construction > *Output the next fenced block as a code block:* @@ -243,11 +264,11 @@ Load **[verify-source-material.md](references/verify-source-material.md)** and f Load **[plan-construction.md](references/plan-construction.md)** and follow its instructions as written. -→ Proceed to **Step 6**. +→ Proceed to **Step 7**. --- -## Step 6: Analyze Task Graph +## Step 7: Analyze Task Graph > *Output the next fenced block as a code block:* @@ -264,11 +285,11 @@ Load **[plan-construction.md](references/plan-construction.md)** and follow its Load **[analyze-task-graph.md](references/analyze-task-graph.md)** and follow its instructions as written. -→ Proceed to **Step 7**. +→ Proceed to **Step 8**. --- -## Step 7: Resolve External Dependencies +## Step 8: Resolve External Dependencies > *Output the next fenced block as a code block:* @@ -285,17 +306,17 @@ Load **[analyze-task-graph.md](references/analyze-task-graph.md)** and follow it #### If work_type is not `epic` -→ Proceed to **Step 8**. +→ Proceed to **Step 9**. #### Otherwise Load **[resolve-dependencies.md](references/resolve-dependencies.md)** and follow its instructions as written. -→ Proceed to **Step 8**. +→ Proceed to **Step 9**. --- -## Step 8: Plan Review +## Step 9: Plan Review > *Output the next fenced block as a code block:* @@ -313,11 +334,11 @@ Load **[resolve-dependencies.md](references/resolve-dependencies.md)** and follo Load **[plan-review.md](references/plan-review.md)** and follow its instructions as written. -→ Proceed to **Step 9**. +→ Proceed to **Step 10**. --- -## Step 9: Compliance Self-Check +## Step 10: Compliance Self-Check > *Output the next fenced block as a code block:* @@ -333,11 +354,11 @@ Load **[plan-review.md](references/plan-review.md)** and follow its instructions Load **[compliance-check.md](../workflow-shared/references/compliance-check.md)** and follow its instructions as written. -→ Proceed to **Step 10**. +→ Proceed to **Step 11**. --- -## Step 10: Conclude the Plan +## Step 11: Conclude the Plan > *Output the next fenced block as a code block:* diff --git a/skills/workflow-planning-process/references/conclude-plan.md b/skills/workflow-planning-process/references/conclude-plan.md index 169a64a8..8771381f 100644 --- a/skills/workflow-planning-process/references/conclude-plan.md +++ b/skills/workflow-planning-process/references/conclude-plan.md @@ -21,7 +21,7 @@ Ready to conclude? #### If `no` -→ Return to **[the skill](../SKILL.md)** for **Step 5**. +→ Return to **[the skill](../SKILL.md)** for **Step 6**. #### If `yes` diff --git a/skills/workflow-research-process/SKILL.md b/skills/workflow-research-process/SKILL.md index 23f60cde..24f65958 100644 --- a/skills/workflow-research-process/SKILL.md +++ b/skills/workflow-research-process/SKILL.md @@ -149,7 +149,49 @@ Load **[research-guidelines.md](references/research-guidelines.md)** and follow --- -## Step 4: Research Session +## Step 4: Knowledge Usage + +> *Output the next fenced block as a code block:* + +``` +── Knowledge Usage ────────────────────────────── +``` + +> *Output the next fenced block as markdown (not a code block):* + +``` +> Loading the usage guide for the knowledge base so +> proactive querying is available throughout the phase. +``` + +Load **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)** and follow its instructions as written. + +→ Proceed to **Step 5**. + +--- + +## Step 5: Contextual Query + +> *Output the next fenced block as a code block:* + +``` +── Contextual Query ───────────────────────────── +``` + +> *Output the next fenced block as markdown (not a code block):* + +``` +> Checking the knowledge base for prior work that relates +> to this research topic before the session begins. +``` + +Load **[contextual-query.md](../workflow-shared/references/contextual-query.md)** and follow its instructions as written. + +→ Proceed to **Step 6**. + +--- + +## Step 6: Research Session > *Output the next fenced block as a code block:* diff --git a/skills/workflow-research-process/references/final-review.md b/skills/workflow-research-process/references/final-review.md index fba1ff6b..0b8ae77e 100644 --- a/skills/workflow-research-process/references/final-review.md +++ b/skills/workflow-research-process/references/final-review.md @@ -6,7 +6,7 @@ A final review ensures the research is thorough before moving to discussion. Even if review agents ran during the session, the research may have progressed significantly since the last one. -This step runs once per "user signals done" entry. It dispatches a fresh review if needed, raises one finding via the shared protocol, then bounces back to the research session so the user can engage naturally. The next time the user signals done, Step 4 re-runs — eventually all findings are drained and the file transitions to `incorporated`, at which point Step 4 returns to the backbone to proceed toward conclusion. +This step runs once per "user signals done" entry. It dispatches a fresh review if needed, raises one finding via the shared protocol, then bounces back to the research session so the user can engage naturally. The next time the user signals done, Step 6 re-runs — eventually all findings are drained and the file transitions to `incorporated`, at which point Step 6 returns to the backbone to proceed toward conclusion. The **never-dump rules apply in full**. Findings are raised one at a time via the shared surfacing protocol. @@ -116,6 +116,6 @@ All findings have been raised (or the review came back with zero gaps). The fina #### If `status: acknowledged` -Either a finding was just raised, or the announce menu was just shown and the user picked `later`. Control belongs to the conversation — return the user to the research session so they can engage naturally. The session loop's check-for-results will pick up subsequent findings at natural breaks. When the user signals done again, Step 4 re-runs and this flow resumes. +Either a finding was just raised, or the announce menu was just shown and the user picked `later`. Control belongs to the conversation — return the user to the research session so they can engage naturally. The session loop's check-for-results will pick up subsequent findings at natural breaks. When the user signals done again, Step 6 re-runs and this flow resumes. -→ Return to **[the skill](../SKILL.md)** for **Step 4**. +→ Return to **[the skill](../SKILL.md)** for **Step 6**. diff --git a/skills/workflow-review-process/SKILL.md b/skills/workflow-review-process/SKILL.md index 75bd50b9..45766b60 100644 --- a/skills/workflow-review-process/SKILL.md +++ b/skills/workflow-review-process/SKILL.md @@ -1,7 +1,7 @@ --- name: workflow-review-process user-invocable: false -allowed-tools: Bash(node .claude/skills/workflow-manifest/scripts/manifest.cjs), Bash(mkdir -p .workflows/.inbox) +allowed-tools: Bash(node .claude/skills/workflow-manifest/scripts/manifest.cjs), Bash(node .claude/skills/workflow-knowledge/scripts/knowledge.cjs), Bash(mkdir -p .workflows/.inbox) --- # Review Process @@ -142,7 +142,7 @@ Set `unreviewed_tasks` = `[{list of unreviewed internal IDs}]`. **If all tasks reviewed:** -→ Proceed to **Step 6**. +→ Proceed to **Step 7**. **Otherwise** (no tracking data): @@ -241,7 +241,28 @@ Load **[load-project-skills.md](references/load-project-skills.md)** and follow --- -## Step 4: QA Verification +## Step 4: Knowledge Usage + +> *Output the next fenced block as a code block:* + +``` +── Knowledge Usage ────────────────────────────── +``` + +> *Output the next fenced block as markdown (not a code block):* + +``` +> Loading the usage guide for the knowledge base so +> proactive querying is available while verifying decisions. +``` + +Load **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)** and follow its instructions as written. + +→ Proceed to **Step 5**. + +--- + +## Step 5: QA Verification > *Output the next fenced block as a code block:* @@ -259,11 +280,11 @@ Load **[load-project-skills.md](references/load-project-skills.md)** and follow Load **[invoke-task-verifiers.md](references/invoke-task-verifiers.md)** and follow its instructions as written. -→ Proceed to **Step 5**. +→ Proceed to **Step 6**. --- -## Step 5: Produce Review +## Step 6: Produce Review > *Output the next fenced block as a code block:* @@ -280,11 +301,11 @@ Load **[invoke-task-verifiers.md](references/invoke-task-verifiers.md)** and fol Load **[produce-review.md](references/produce-review.md)** and follow its instructions as written. -→ Proceed to **Step 6**. +→ Proceed to **Step 7**. --- -## Step 6: Present Review +## Step 7: Present Review > *Output the next fenced block as a code block:* @@ -301,11 +322,11 @@ Load **[produce-review.md](references/produce-review.md)** and follow its instru Load **[present-review.md](references/present-review.md)** and follow its instructions as written. -→ Proceed to **Step 7**. +→ Proceed to **Step 8**. --- -## Step 7: Compliance Self-Check +## Step 8: Compliance Self-Check > *Output the next fenced block as a code block:* @@ -321,11 +342,11 @@ Load **[present-review.md](references/present-review.md)** and follow its instru Load **[compliance-check.md](../workflow-shared/references/compliance-check.md)** and follow its instructions as written. -→ Proceed to **Step 8**. +→ Proceed to **Step 9**. --- -## Step 8: Review Actions +## Step 9: Review Actions > *Output the next fenced block as a code block:* diff --git a/skills/workflow-review-process/references/produce-review.md b/skills/workflow-review-process/references/produce-review.md index 7be5b718..d524f463 100644 --- a/skills/workflow-review-process/references/produce-review.md +++ b/skills/workflow-review-process/references/produce-review.md @@ -8,7 +8,7 @@ Aggregate QA findings into a review document using the **[template.md](template. Write the review to `.workflows/{work_unit}/review/{topic}/report.md`. The review is always per-plan. -**QA Verdict** (from Step 4): +**QA Verdict** (from Step 5): - **Approve** — All acceptance criteria met, no blocking issues - **Request Changes** — Missing requirements, broken functionality, inadequate tests - **Comments Only** — Minor suggestions, non-blocking observations diff --git a/skills/workflow-scoping-process/SKILL.md b/skills/workflow-scoping-process/SKILL.md index 0e41d063..2845476d 100644 --- a/skills/workflow-scoping-process/SKILL.md +++ b/skills/workflow-scoping-process/SKILL.md @@ -89,7 +89,7 @@ node .claude/skills/workflow-manifest/scripts/manifest.cjs init-phase {work_unit node .claude/skills/workflow-manifest/scripts/manifest.cjs set {work_unit}.scoping.{topic} status completed ``` -→ Proceed to **Step 6**. +→ Proceed to **Step 7**. **Otherwise:** @@ -101,7 +101,28 @@ node .claude/skills/workflow-manifest/scripts/manifest.cjs set {work_unit}.scopi --- -## Step 1: Gather Context +## Step 1: Knowledge Usage + +> *Output the next fenced block as a code block:* + +``` +── Knowledge Usage ────────────────────────────── +``` + +> *Output the next fenced block as markdown (not a code block):* + +``` +> Loading the usage guide for the knowledge base so +> proactive querying is available while scoping the change. +``` + +Load **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)** and follow its instructions as written. + +→ Proceed to **Step 2**. + +--- + +## Step 2: Gather Context > *Output the next fenced block as a code block:* @@ -118,11 +139,11 @@ node .claude/skills/workflow-manifest/scripts/manifest.cjs set {work_unit}.scopi Load **[gather-context.md](references/gather-context.md)** and follow its instructions as written. -→ Proceed to **Step 2**. +→ Proceed to **Step 3**. --- -## Step 2: Complexity Check +## Step 3: Complexity Check > *Output the next fenced block as a code block:* @@ -139,11 +160,11 @@ Load **[gather-context.md](references/gather-context.md)** and follow its instru Load **[complexity-check.md](references/complexity-check.md)** and follow its instructions as written. -→ Proceed to **Step 3**. +→ Proceed to **Step 4**. --- -## Step 3: Write Specification +## Step 4: Write Specification > *Output the next fenced block as a code block:* @@ -160,11 +181,11 @@ Load **[complexity-check.md](references/complexity-check.md)** and follow its in Load **[write-specification.md](references/write-specification.md)** and follow its instructions as written. -→ Proceed to **Step 4**. +→ Proceed to **Step 5**. --- -## Step 4: Select Output Format +## Step 5: Select Output Format > *Output the next fenced block as a code block:* @@ -180,11 +201,11 @@ Load **[write-specification.md](references/write-specification.md)** and follow Load **[select-format.md](references/select-format.md)** and follow its instructions as written. -→ Proceed to **Step 5**. +→ Proceed to **Step 6**. --- -## Step 5: Write Tasks +## Step 6: Write Tasks > *Output the next fenced block as a code block:* @@ -201,11 +222,11 @@ Load **[select-format.md](references/select-format.md)** and follow its instruct Load **[write-tasks.md](references/write-tasks.md)** and follow its instructions as written. -→ Proceed to **Step 6**. +→ Proceed to **Step 7**. --- -## Step 6: Conclude Scoping +## Step 7: Conclude Scoping > *Output the next fenced block as a code block:* diff --git a/skills/workflow-shared/references/contextual-query.md b/skills/workflow-shared/references/contextual-query.md new file mode 100644 index 00000000..a27c7319 --- /dev/null +++ b/skills/workflow-shared/references/contextual-query.md @@ -0,0 +1,56 @@ +# Contextual Query + +*Shared reference for research, discussion, and investigation processing skills.* + +--- + +At the beginning of these phases, a single targeted query against the knowledge base catches prior work that might otherwise surface as a correction ten minutes into the session. One query, one interpretation step — if nothing comes back, proceed as normal. + +This is **not** a speculative dump. It is a focused check using the best context currently available. + +## A. Construct the query + +Build a short natural-language description of what this phase is about using whatever context you have at hand: the topic description, the handoff context, bootstrap answers already captured, the problem statement, and — for investigation — the initial symptoms. + +- **Do** describe the thing in the language the original author would have used. +- **Do not** use the topic slug. `"auth-flow"` is a weak semantic signal; `"user authentication flow using OAuth2 with PKCE for mobile and web clients"` is strong. +- **Do** run a batch query (multiple angles) if you have several distinct framings — one for the feature, one for the constraint, one for the suspected dependency. Batch queries are a single CLI call. + +If the only context available is a topic name, construct the best descriptive query you can. A poor query that returns nothing is acceptable — the cost is one store load. + +## B. Run the query + +Invoke the CLI with the constructed query (or queries). Use `--work-unit {work_unit}` to bias results toward the current work unit without filtering out cross-work-unit context. Do not use hard filters unless you have a specific reason — this is meant to surface prior work broadly. + +``` +node .claude/skills/workflow-knowledge/scripts/knowledge.cjs query "" --work-unit {work_unit} +``` + +#### If the command exits with a non-zero code + +→ Load **[knowledge-usage.md](knowledge-usage.md)** for **D. Query failure handling** and follow its instructions. + +## C. Interpret the results + +#### If stdout is `[0 results]` + +No prior context found. Proceed to the next step silently — no delay, no user noise. + +→ Return to caller. + +#### If results are returned + +Read each chunk and weigh it against the current topic. For a chunk that looks load-bearing, read its source file (the `Source:` line) for full detail. Most results are context — one or two may be directly relevant. + +Briefly acknowledge surfaced context to the user before the main session starts: + +> *Output the next fenced block as markdown (not a code block):* + +``` +> Surfaced prior context from the knowledge base — incorporating into this phase. +> {One short line naming the most relevant piece, e.g. "auth-flow decided on UUID identity (spec, 2026-03-15)."} +``` + +Carry the context forward into the phase. Do not dump the full chunk list to the user — summarise only if the user asks, or if a chunk materially changes how this phase should start. + +→ Return to caller. diff --git a/skills/workflow-shared/references/knowledge-usage.md b/skills/workflow-shared/references/knowledge-usage.md new file mode 100644 index 00000000..08d0faf0 --- /dev/null +++ b/skills/workflow-shared/references/knowledge-usage.md @@ -0,0 +1,99 @@ +# Knowledge Usage + +*Shared reference for processing skills (research, discussion, investigation, scoping, planning, implementation, review).* + +--- + +This reference sets expectations for how you use the knowledge base *during* a phase — when to query, how to construct queries, how to interpret results, and what to do if a query fails. Load it early in the phase so the guidance is active from the first substantive step. + +For API details (commands, flags, output format, confidence tiers, two-step retrieval), load **[SKILL.md](../../workflow-knowledge/SKILL.md)** — the knowledge skill's API documentation. + +--- + +## A. When to query + +Query proactively throughout the phase. Under-querying is the bigger risk — the knowledge base is cheap to check and valuable when prior work exists. Trust your judgement and err on the side of querying. + +Four trigger heuristics. If any fires, query: + +1. **Topic boundaries** — the conversation is at the edge of the current topic, brushing up against adjacent territory that may have been explored elsewhere. ("This auth discussion is starting to touch session handling — was that covered in another work unit?") +2. **Upstream/downstream dependencies** — something being discussed might affect or be affected by other parts of the system. ("This data-model change has implications for billing — have we discussed billing's assumptions about this field?") +3. **Unfamiliar territory** — you're not sure whether a topic has been explored before in this project. When in doubt, check. +4. **User prompts** — the user asks "have we discussed this?", "is there prior context?", "what was decided about X?", or anything similar. + +Multiple queries from different angles are expected and encouraged. One query for the decision, one for the constraint, one for the rejected alternative — each surfaces different context. + +## B. How to construct queries + +Use **natural language** describing what you're looking for. Not topic slugs — slugs are weak semantic signal. A query should read like a sentence the original author would have written. + +- Good: `"OAuth2 PKCE flow for mobile clients"` +- Good: `"why we ruled out email as a primary identity field"` +- Poor: `"auth-flow"` (slug, weak signal) +- Poor: `"auth"` (too broad) + +Use the CLI flags to filter, not the query string: + +- `--work-type ` — filter to a work type (hard filter) +- `--phase ` — filter to a phase (hard filter) +- `--topic ` — filter to a topic (hard filter) +- `--work-unit ` — **re-ranking hint, not a filter** — boosts results from the current work unit while still returning cross-work-unit context + +For batch queries (multiple angles in one invocation), pass multiple positional terms. See the knowledge skill for details. + +## C. Two-step retrieval + +Results include chunks with provenance. Don't read source files for every chunk — read only when a chunk looks load-bearing for what you're doing. The chunk text alone is usually enough to judge relevance; the source file is there for deep dives. + +## D. Query failure handling + +If `knowledge query` exits with a non-zero code, **pause the workflow**. Do not silently proceed without context — the knowledge base is high-value enough that silent skips are worse than a brief interruption. + +1. Capture the error output. +2. Surface it to the user using the display block below. +3. Offer two options — fix and retry, or explicitly proceed without knowledge. +4. If the user chooses to proceed, continue the phase but record that knowledge retrieval was skipped so the user knows context may be missing. + +> *Output the next fenced block as a code block:* + +``` +⚑ Knowledge query failed + {error output} + + Likely causes: expired API key, network outage, corrupted store, + or provider mismatch. Run `knowledge status` to diagnose. +``` + +> *Output the next fenced block as markdown (not a code block):* + +``` +· · · · · · · · · · · · +How should I proceed? + +- **`r`/`retry`** — I'll fix the issue; retry the query +- **`s`/`skip`** — Proceed without knowledge context for this phase +· · · · · · · · · · · · +``` + +**STOP.** Wait for user response. + +#### If `retry` + +Re-run the query. If it fails again, surface again. Same choice. + +#### If `skip` + +Note in the current phase's working file that the knowledge query was skipped and continue. Example: append a short note under a relevant section — *"Knowledge base query skipped ({YYYY-MM-DD}) — prior context may be missing."* — so the user can audit later. + +## E. Phase-specific notes + +- **Research** — query at the start of the phase (via the contextual query step) and throughout. Early phases have the highest chance of overlapping with prior work — research is often where the same ground gets explored twice if we don't check. +- **Discussion** — query at the start and throughout. Decisions being made now often echo or contradict decisions made elsewhere. Check before committing to a direction. +- **Investigation** — query at the start (after initial symptoms are gathered) and throughout. Symptoms and root causes may have been seen before — a matching prior investigation can save hours. +- **Specification** — **do not query during this phase.** The spec turns discussion decisions into a golden document. Cross-cutting concerns merge at planning time via an explicit cross-cutting query, not during spec authoring. Querying mid-spec pulls the document away from its own source material. +- **Scoping** — query throughout. Quick-fix scoping benefits from knowing if the issue was discussed or investigated elsewhere — a "mechanical change" often has a history. +- **Planning** — query throughout, especially when designing phases and tasks. Cross-cutting context is handled explicitly at planning entry (a targeted `--work-type cross-cutting` query replaces the old manual approach) — don't duplicate that work here. +- **Implementation** — query when a task touches unfamiliar territory or intersects with areas covered by prior work. Use it to check assumptions before writing code, not to retro-justify decisions after. +- **Review** — query to verify decisions against prior context. When something in the implementation looks inconsistent with how similar decisions were made elsewhere, the knowledge base is the quickest way to check. + +→ Return to caller. From cae8f1abd3d7adbf7207e782fca172a4c6c27b8e Mon Sep 17 00:00:00 2001 From: Lee Overy Date: Sat, 18 Apr 2026 20:13:43 +0100 Subject: [PATCH 3/9] feat(knowledge): add Layer 3 inline callouts + planning entry cross-cutting query MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds short inline nudges at high-value moments in all processing skills except specification (research, discussion, investigation, scoping, planning, implementation, review) — brief reminders to query the knowledge base at decision points, root cause synthesis, task entry, etc. Not new steps; embedded at step boundaries. Replaces planning-entry's manual cross-cutting spec reader with a targeted semantic query (--work-type cross-cutting --phase specification), keeping the in-progress-cross-cutting warning intact. Query text is built from the topic's spec summary, not the slug. Adds knowledge.cjs to planning-entry allowed-tools. Co-Authored-By: Claude Opus 4.7 (1M context) --- .tick/tasks.jsonl | 4 +- skills/workflow-discussion-process/SKILL.md | 2 + .../workflow-implementation-process/SKILL.md | 2 + .../workflow-investigation-process/SKILL.md | 2 + skills/workflow-planning-entry/SKILL.md | 2 +- .../references/cross-cutting-context.md | 74 +++++++++++-------- skills/workflow-planning-process/SKILL.md | 2 + skills/workflow-research-process/SKILL.md | 2 + skills/workflow-review-process/SKILL.md | 2 + skills/workflow-scoping-process/SKILL.md | 2 + 10 files changed, 62 insertions(+), 32 deletions(-) diff --git a/.tick/tasks.jsonl b/.tick/tasks.jsonl index 6c785366..09924428 100644 --- a/.tick/tasks.jsonl +++ b/.tick/tasks.jsonl @@ -25,10 +25,10 @@ {"id":"tick-7d74fe","title":"Hard Stop Reference + Step 0 Integration","status":"done","priority":2,"type":"task","refs":["knowledge-base-5-1"],"description":"Problem: Entry-point skills need to gate on knowledge base readiness before proceeding. Without this gate, skills would attempt to query or index against a non-existent knowledge base. The design doc makes the knowledge base required infrastructure — no graceful degradation, just a clear hard stop with setup instructions.\n\nSolution: Create a hard stop reference file and update Step 0 in all 11 entry-point skills to run knowledge check after migrations, display the hard stop if not ready, and run knowledge compact if ready.\n\nOutcome: Every workflow invocation checks knowledge base readiness before proceeding, with a clear user-facing message when setup is needed, and automatic compaction keeping the index lean.\n\nDo:\n\nHARD STOP REFERENCE FILE:\n- Create skills/workflow-shared/references/knowledge-not-ready.md (or similar shared location — check where other shared references live).\n- This file is loaded and displayed when knowledge check returns not-ready.\n- Content should follow the existing hard stop / terminal condition conventions from CLAUDE.md:\n - Phase title box explaining what happened\n - Signpost blockquote explaining why the knowledge base is needed\n - Clear instruction: run knowledge setup to initialise\n - The exact command: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs setup\n - Brief explanation of what setup does (system config, project init, initial indexing)\n - Mention stub mode is available if no API key\n - Terminal stop — do not proceed\n- Follow the display conventions from CLAUDE.md: phase title (bullet-bordered box), signpost blockquote, rendering instructions.\n\nSTEP 0 CHANGES:\n- Update Step 0 in ALL 11 entry-point skills. The affected files:\n skills/start-feature/SKILL.md\n skills/start-epic/SKILL.md\n skills/start-bugfix/SKILL.md\n skills/start-quickfix/SKILL.md\n skills/start-cross-cutting/SKILL.md\n skills/continue-feature/SKILL.md\n skills/continue-epic/SKILL.md\n skills/continue-bugfix/SKILL.md\n skills/continue-quickfix/SKILL.md\n skills/continue-cross-cutting/SKILL.md\n skills/workflow-start/SKILL.md\n\n- The Step 0 sequence after this change:\n 1. Migrations (existing — preserve as-is)\n 2. Knowledge check: run node .claude/skills/workflow-knowledge/scripts/knowledge.cjs check and capture stdout.\n - If stdout is not-ready: load the hard stop reference file and follow its instructions. STOP — do not proceed.\n - If stdout is ready: proceed.\n 3. Knowledge compact: run node .claude/skills/workflow-knowledge/scripts/knowledge.cjs compact (no flags — not dry-run). This is silent when nothing to compact. Output only appears if chunks were removed.\n\n- The existing Step 0 structure varies between start-* and continue-* skills:\n - start-* skills CHECK if /workflow-migrate has been invoked (they expect it was already run)\n - continue-* and workflow-start ACTIVELY run migrations if not done\n The knowledge check + compact goes AFTER the migration handling in both cases. Read each skill's Step 0 to understand its current structure before modifying.\n\n- Each skill's Step 0 will need its own rendering instruction for the check result / compact output if applicable. Follow the existing conventions in each skill.\n\nALLOWED-TOOLS:\n- Add Bash(node .claude/skills/workflow-knowledge/scripts/knowledge.cjs) to the allowed-tools frontmatter of all 11 entry-point skills.\n- This follows the same pattern as the manifest CLI allowed-tools entries already in these files. Check one skill first to see the exact format.\n\nAcceptance Criteria:\n- Hard stop reference file exists and follows display conventions\n- All 11 entry-point skills have knowledge check in Step 0 after migrations\n- knowledge check returning not-ready loads the hard stop reference and stops\n- knowledge check returning ready proceeds normally\n- All 11 entry-point skills run knowledge compact after successful check\n- Compact output is visible when chunks are removed, silent when nothing to compact\n- allowed-tools frontmatter updated in all 11 entry-point skills\n- Existing migration handling in Step 0 is preserved and unmodified\n- The Step 0 ordering is: migrations -\u003e knowledge check -\u003e knowledge compact\n\nTests:\n- No automated tests for this task — it is a skill file editing task. Validation is manual:\n - Invoke a start-* skill with no knowledge base set up -\u003e verify hard stop appears\n - Invoke a continue-* skill with knowledge base set up -\u003e verify check passes and compact runs\n - Verify allowed-tools entries are present in all 11 files\n\nEdge Cases:\n- knowledge check fails with a genuine error (not not-ready, but a crash) — the skill should surface the error, not silently proceed. Check exit code: 0 is expected (ready or not-ready on stdout). Non-zero means something broke.\n- knowledge compact fails (e.g., store locked) — should surface the error but not hard-stop the workflow. Compaction failure is a warning, not a blocker. The knowledge base still works, just with stale chunks.\n- Existing Step 0 in start-* skills only checks if migrations were invoked — adding knowledge steps must not change this conditional structure. The check and compact are unconditional additions after the migration section.\n\nSpec Reference: knowledge-base/design.md — Knowledge Base is Required Infrastructure section (lines 304-320, setup flow, hard stop), Compaction Trigger section (lines 847-855, Step 0 sequence: migrations -\u003e check -\u003e compact), allowed-tools frontmatter changes (lines 728-733)","transitions":[{"from":"open","to":"in_progress","at":"2026-04-16T20:07:42Z","auto":false},{"from":"in_progress","to":"done","at":"2026-04-16T20:14:06Z","auto":false}],"parent":"tick-77697a","created":"2026-04-09T08:19:17Z","updated":"2026-04-16T20:14:06Z","closed":"2026-04-16T20:14:06Z"} {"id":"tick-055556","title":"Phase Completion Indexing","status":"done","priority":2,"type":"task","refs":["knowledge-base-5-2"],"description":"Problem: The knowledge base needs to grow automatically as workflow phases complete. Without automatic indexing at phase completion, users would need to manually run knowledge index after every discussion, research session, investigation, or specification — which would never happen consistently.\n\nSolution: Add knowledge index \u003cfile\u003e calls at the phase completion points in processing skills for all indexed phases, plus scoping (which produces a spec). Also audit the skills/ directory for every place that transitions a work unit to status: completed and add completed_at alongside each one.\n\nOutcome: Every completed workflow artifact is automatically indexed into the knowledge base, and every work unit completion path sets completed_at for the compact command's TTL calculation.\n\nDo:\n- Add knowledge index \u003cfile\u003e at the phase completion step in each of these processing skills:\n\n skills/workflow-research-process/SKILL.md\n skills/workflow-discussion-process/SKILL.md\n skills/workflow-investigation-process/SKILL.md\n skills/workflow-specification-process/SKILL.md\n skills/workflow-scoping-process/SKILL.md\n\n- For each skill, find the step where the phase artifact is finalised and committed. The index call goes AFTER the artifact is saved to disk and committed, but BEFORE any phase transition or handoff to the next phase. The artifact must exist on disk before indexing.\n\n- The index call pattern:\n Run: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs index \u003cartifact_path\u003e\n Where \u003cartifact_path\u003e is the path to the completed artifact file. Each phase has a different path convention:\n - Research: .workflows/{work_unit}/research/{topic}.md (may vary — use the actual file that was just written)\n - Discussion: .workflows/{work_unit}/discussion/{topic}.md\n - Investigation: .workflows/{work_unit}/investigation/{topic}.md\n - Specification: .workflows/{work_unit}/specification/{topic}/specification.md\n - Scoping: produces a specification — index the spec file it creates, NOT a scoping artifact (scoping is not an indexed phase per design doc)\n\n- The index call should reference the actual file path variable/value used in the skill, not a hardcoded path. Read each skill to understand how it references the artifact file.\n\n- FAILURE HANDLING: indexing failure must NOT block the phase. The artifact is already saved. If knowledge index fails, output the error message (which includes retry-failed + pending queue info from Task 4-4) and continue with the phase transition. The design doc is explicit: the phase itself is not blocked — the artifact is saved. But the failure is made visible, not silently swallowed.\n\n- MULTIPLE INDEXED ARTIFACTS: some skills may complete multiple artifacts. For example, scoping produces both a specification and potentially sets up planning. Only the spec needs indexing. Each index call is independent — a failure on one does not block the other (per design doc line 707).\n\nCOMPLETED_AT AUDIT (concrete instruction, not judgement call):\n- The completed_at field (added by the migration in Task 4-2) needs to be set going forward whenever ANY code path transitions a work unit to status: completed. Missing a path means the work unit will never expire under compaction (Task 4-5 handles missing completed_at defensively, but the result is silent non-compaction).\n- AUDIT STEP: grep the skills/ directory for every place that sets status to completed. Suggested grep patterns:\n grep -rn 'status.*completed' skills/\n grep -rn 'manifest.cjs set.*status.*completed' skills/\n grep -rn 'completed' skills/ | grep -i status\n- For EACH match, add a manifest.cjs set {work_unit} completed_at {current_date_ISO} call alongside the status-setting call. Format: YYYY-MM-DD (ISO date, same as the migration backfill in Task 4-2).\n- Known locations (verified to exist — the grep is still the authoritative source, but these are the high-traffic files):\n - skills/workflow-bridge/references/ — 5 continuation files set status: completed (bugfix-continuation.md, feature-continuation.md, epic-continuation.md, cross-cutting-continuation.md, quickfix-continuation.md). Bridge is where most feature/bugfix/quickfix completions happen — do not miss these.\n - The 5 processing skills listed above (research, discussion, investigation, specification, scoping) — conclude-*.md references\n - skills/workflow-review-process/references/review-actions-loop.md — review is often the last phase and may mark the work unit completed\n - skills/workflow-implementation-process/references/conclude-implementation.md — implementation completion\n - skills/workflow-specification-process/references/spec-completion.md and promote-to-cross-cutting.md — specification lifecycle\n - skills/workflow-scoping-process/references/write-tasks.md and write-specification.md — scoping completion paths\n - skills/workflow-start/references/manage-work-unit.md — the manage menu done action, covered by Task 5-3\n- DO NOT rely on the list above being exhaustive. The grep is the authoritative source of truth. Add completed_at setting wherever the grep finds status: completed being set, even if the file is not in the list above.\n- Report the full list of files modified (for review) when completing this task.\n- Acceptance post-condition: after editing, grep -rn 'status.*completed' skills/ should show every match adjacent (same step or reference block) to a corresponding completed_at set. This is a mechanical check the implementer can run to self-verify coverage.\n\n- Add allowed-tools for knowledge.cjs to these 5 processing skills (if not already added by Task 5-1 or Task 5-3).\n\nAcceptance Criteria:\n- Research process skill indexes the research artifact on completion\n- Discussion process skill indexes the discussion artifact on completion\n- Investigation process skill indexes the investigation artifact on completion\n- Specification process skill indexes the specification artifact on completion\n- Scoping process skill indexes the spec it produces on completion\n- Index failure does not block the phase — error is displayed, phase continues\n- Every place in skills/ that sets status: completed also sets completed_at (verified via grep audit)\n- All 5 bridge continuation files are updated (bugfix, feature, epic, cross-cutting, quickfix)\n- The list of files modified for completed_at is documented in the task completion report\n- Post-condition grep shows every status: completed match adjacent to a completed_at set\n- allowed-tools updated in all 5 processing skills\n\nTests:\n- No automated tests — skill file editing task. Validation is manual:\n - Complete a discussion in a test project -\u003e verify chunks appear in knowledge base (knowledge status shows them)\n - Complete a specification -\u003e verify chunks appear\n - Simulate index failure (e.g., corrupt store) -\u003e verify phase still completes, error is shown\n - Grep skills/ after task completion: every status-completed line should have a neighbouring completed_at line\n\nEdge Cases:\n- Scoping produces a spec but scoping itself is not an indexed phase — only the spec output is indexed. The index call must reference the spec file path, not a scoping artifact path.\n- Research in epics can produce multiple files — each file may need separate indexing. Check how the research process skill handles multiple outputs. If it produces one file per research topic, each gets its own index call.\n- completed_at audit finds a skill that doesn't import the manifest CLI — check the skill's allowed-tools and add if needed\n- Phase completion with no artifact file (edge case — should not happen in normal flow) — knowledge index will error on missing file, which is correct and visible.\n- A skill sets status: completed on a DIFFERENT work unit than its own (e.g., the manage menu) — this is covered by Task 5-3 for the manage menu specifically.\n- Bridge continuation files may set completed on a SOURCE work unit when transitioning (e.g., a feature completion closing out the feature before bridging to the next). Ensure completed_at is set on the same work unit whose status is being set.\n\nSpec Reference: knowledge-base/design.md — Indexing section (lines 337-341, primary trigger is phase completion, not mid-phase), Integration with Workflow Skills section (lines 707-708, indexing at phase completion, independent per artifact, failure does not block), completed_at field (line 824-829, set explicitly by skill at completion time going forward, the manage menu done action and any skill that sets status: completed must also set completed_at)","transitions":[{"from":"open","to":"in_progress","at":"2026-04-16T20:14:29Z","auto":false},{"from":"in_progress","to":"done","at":"2026-04-16T20:19:31Z","auto":false}],"parent":"tick-77697a","created":"2026-04-09T17:54:59Z","updated":"2026-04-16T20:19:31Z","closed":"2026-04-16T20:19:31Z"} {"id":"tick-f84af0","title":"Lifecycle Removal (Cancellation + Supersession/Promotion)","status":"done","priority":2,"type":"task","refs":["knowledge-base-5-3"],"description":"Problem: When work units are cancelled or specs are superseded/promoted, their chunks must be removed from the knowledge base. Without this, stale and contradictory information pollutes search results. Additionally, the manage menu's done action needs to set completed_at for compaction TTL calculation.\n\nSolution: Add knowledge remove calls to the manage menu reference (cancellation) and specification process (supersession/promotion) skills. Add completed_at setting to the manage menu's done action.\n\nOutcome: Work unit cancellation and spec lifecycle changes automatically clean the knowledge base, and completed work units have the timestamp needed for decay compaction.\n\nDo:\n\nCANCELLATION REMOVAL (manage menu reference):\n- The manage menu lives inside the workflow-start skill at skills/workflow-start/references/manage-work-unit.md (NOT a separate workflow-manage skill — verified).\n- Locate the cancellation action in that file (where status is set to cancelled).\n- Add inline: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs remove --work-unit {work_unit}\n- This runs INLINE as part of the cancellation action — no prompt, cancelling means done with it (design doc line 801).\n- If removal fails (store locked, CLI error): log the error visibly but do not block the cancellation. The pending queue is designed for indexing failures, not removal failures. If removal fails, output the error and note that the user can run knowledge remove manually.\n- NO frontmatter edit is needed here — skills/workflow-start is an entry-point skill that already receives allowed-tools for knowledge.cjs in Task 5-1. The reference file inherits from its parent skill.\n\nCOMPLETED_AT ON DONE ACTION (manage menu reference):\n- Locate the done/completion action in skills/workflow-start/references/manage-work-unit.md (where status is set to completed).\n- Add: manifest.cjs set {work_unit} completed_at {current_date_ISO}\n- The completed_at field is what compaction (Task 4-5) uses to calculate decay TTL. Without it, completed work units cannot expire and the index grows without bound.\n- This complements Task 5-2 which adds completed_at in processing skills and bridge continuations where completion happens automatically. The manage menu is where users manually mark work units as done — both paths must set the field.\n- Format: YYYY-MM-DD (ISO date, same as the migration backfill in Task 4-2).\n\nSUPERSESSION REMOVAL (specification process skill):\n- Find the specification process skill: skills/workflow-specification-process/SKILL.md\n- Locate the supersession action — where a spec's manifest status changes to superseded.\n- Add: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs remove --work-unit {work_unit} --phase specification --topic {topic}\n- This removes ONLY the superseded topic's spec chunks. Other topics in the same work unit (e.g., other specs in an epic) are unaffected. Granularity matters (design doc line 656).\n- The specification process skill already has allowed-tools for knowledge.cjs from Task 5-2 (for indexing). No additional frontmatter change needed.\n\nPROMOTION REMOVAL (specification process skill):\n- Locate the promotion action — where a spec's manifest status changes to promoted.\n- Add the same remove command: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs remove --work-unit {work_unit} --phase specification --topic {topic}\n- Promotion is a RELOCATION, not a deletion (design doc line 535). The chunks are removed from the original work unit. The new cross-cutting spec will be indexed naturally when it completes in the new work unit. There is a timing gap where the content is absent from the knowledge base — this is accepted per design doc line 537.\n- Research, discussion, and investigation chunks from the original work unit are KEPT — only the spec chunks are removed (design doc line 539).\n\nALLOWED-TOOLS SUMMARY FOR PHASE 5:\n- Task 5-1 adds to 11 entry-point skills (for check + compact). workflow-start is one of them, which covers the manage-work-unit.md reference file used by this task.\n- Task 5-2 adds to 5 indexed phase processing skills (for index), and updates bridge continuation files.\n- This task adds NO new allowed-tools entries — all target files are covered by Tasks 5-1 or 5-2.\n- Total Phase 5 allowed-tools changes: 16 skills (11 from 5-1 + 5 from 5-2).\n- The 3 non-indexed processing skills (planning, implementation, review) get allowed-tools in Phase 6 Task 6-2 when autonomous querying is added — no Phase 5 reason to add them now.\n- Phase entry skills (workflow-*-entry) do NOT get allowed-tools in Phase 5. The one exception is workflow-planning-entry, which gets allowed-tools in Phase 6 Task 6-3 specifically for the cross-cutting query. No other phase entry skill needs it.\n\nAcceptance Criteria:\n- Cancelling a work unit via manage menu removes its chunks from the knowledge base\n- Cancellation removal failure does not block the cancellation action\n- Manage menu done action sets completed_at on the work unit manifest\n- Superseding a spec removes only that topic's spec chunks\n- Promoting a spec removes only that topic's spec chunks from the original work unit\n- Research/discussion/investigation chunks from the same work unit survive supersession and promotion\n- No new allowed-tools frontmatter edits in this task (covered by Task 5-1 for workflow-start, Task 5-2 for specification-process)\n\nTests:\n- No automated tests — skill file editing task. Validation is manual:\n - Cancel a work unit that has indexed chunks -\u003e verify chunks are removed (knowledge status)\n - Mark a work unit as done via manage menu -\u003e verify completed_at is set in manifest\n - Supersede a spec topic in an epic -\u003e verify only that topic's spec chunks are removed, other topics and non-spec phases survive\n\nEdge Cases:\n- Cancellation of a work unit that was never indexed — knowledge remove returns 0 removed, no error. The cancellation flow should not treat this as a failure.\n- Supersession of a spec that was never indexed — same, 0 removed, no error.\n- Promotion timing gap — between removing original spec chunks and the new cross-cutting spec completing, the content is absent from the knowledge base. This is accepted per design doc.\n- Epic with multiple spec topics — superseding one MUST NOT remove others. The --topic flag ensures granularity.\n- Done action on a work unit that already has completed_at — overwrite with current date (the user is explicitly marking it done now, regardless of previous state).\n\nSpec Reference: knowledge-base/design.md — Work Unit Lifecycle section (lines 799-801, cancelled work units auto-removed, failure handling), Staleness and Supersession section (lines 530-539, superseded removed, promoted relocated, research/discussion/investigation kept), completed_at prerequisite (line 824, manage menu done action must set it), allowed-tools frontmatter changes (lines 728-733)","transitions":[{"from":"open","to":"in_progress","at":"2026-04-16T20:19:57Z","auto":false},{"from":"in_progress","to":"done","at":"2026-04-16T20:20:59Z","auto":false}],"parent":"tick-77697a","created":"2026-04-09T17:58:53Z","updated":"2026-04-16T20:20:59Z","closed":"2026-04-16T20:20:59Z"} -{"id":"tick-496c59","title":"Phase 6: Retrieval Integration","status":"in_progress","priority":2,"refs":["knowledge-base-6"],"transitions":[{"from":"open","to":"in_progress","at":"2026-04-18T18:59:31Z","auto":true}],"parent":"tick-cbbd13","created":"2026-04-09T18:09:56Z","updated":"2026-04-18T18:59:31Z"} +{"id":"tick-496c59","title":"Phase 6: Retrieval Integration","status":"done","priority":2,"refs":["knowledge-base-6"],"transitions":[{"from":"open","to":"in_progress","at":"2026-04-18T18:59:31Z","auto":true},{"from":"in_progress","to":"done","at":"2026-04-18T19:13:35Z","auto":true}],"parent":"tick-cbbd13","created":"2026-04-09T18:09:56Z","updated":"2026-04-18T19:13:35Z","closed":"2026-04-18T19:13:35Z"} {"id":"tick-09d9ca","title":"Knowledge SKILL.md + Two-Step Retrieval Documentation","status":"done","priority":2,"type":"task","refs":["knowledge-base-6-1"],"description":"Problem: The knowledge base CLI exists (Phases 1-4) and is wired into skills (Phase 5), but Claude has no documentation explaining what it is, how to use it, or when to query it. Without Layer 1, Layers 2 and 3 have nothing to reference for API details.\n\nSolution: Create the knowledge skill file (SKILL.md) that serves as the API documentation layer — what commands exist, how to call them, what the output looks like, and how the two-step retrieval pattern works.\n\nOutcome: A comprehensive skill file that any processing skill can reference for knowledge base API details, enabling Claude to query the knowledge base correctly.\n\nDo:\n- Create skills/workflow-knowledge/SKILL.md following the project's skill file conventions (see CLAUDE.md Skill File Structure section).\n- This is a model-invocable skill, not user-invocable. It is loaded by reference from Layer 2 usage references (Task 6-2). It is NOT directly invoked by users.\n- Content sections:\n\n PURPOSE:\n - What the knowledge base is: a RAG system storing all workflow artifacts at full fidelity for semantic search\n - Why it exists: cross-work-unit and intra-work-unit context surfacing\n - What it indexes: research, discussion, investigation, specification (not planning, implementation, review)\n\n QUERY COMMAND:\n - Single query: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs query \u003csearch_term\u003e [flags]\n - Batch query: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs query \u003cterm1\u003e \u003cterm2\u003e [termN...] [flags]\n Multiple positional arguments run separate searches, merge results, deduplicate by chunk ID (highest score kept), apply --limit to merged set. Efficient: one store load, multiple searches.\n - Flags: --work-type, --phase, --work-unit (re-ranking hint, not filter), --limit\n - Search modes: hybrid (default when provider configured), keyword-only (when no provider)\n - Query construction guidance: use natural language, not topic slugs. Descriptive queries produce better semantic matching. Multiple queries from different angles are encouraged.\n - Example queries showing good vs poor query construction\n\n OUTPUT FORMAT:\n - Document the exact format (from design doc lines 580-603):\n [N results]\n [phase | work_unit/topic | confidence | YYYY-MM-DD]\n chunk content verbatim\n Source: source_file_path\n - Result count header, provenance line, verbatim content, source path\n - Empty results: [0 results]\n - Stub mode note when applicable: [keyword-only mode — configure embedding provider for semantic search]\n\n CONFIDENCE TIERS:\n - Explain what confidence means and how to weigh it:\n specification (high) — validated decisions, what was decided and why\n investigation (medium) — diagnostic knowledge, tied to specific symptoms\n discussion (low-medium) — conversational, may contain corrected assumptions\n research (low) — exploratory, may contain dead ends and rejected paths\n - Low confidence is not low value — research that rejected an approach prevents re-exploring dead ends\n\n TWO-STEP RETRIEVAL PATTERN:\n - Step 1: query returns chunks with provenance (lightweight, lands in context)\n - Step 2: if a chunk looks relevant, read the actual source file (source_file in metadata) for full detail\n - This keeps context lean — surface-level awareness, deep dive on demand\n - Claude should NOT read source files for every result, only when a chunk warrants deeper investigation\n\n WHAT NOT TO DO:\n - Do not dump large result sets into context speculatively\n - Do not query using topic slugs as search terms (poor semantic signal)\n - Do not query during specification phase (explicitly excluded — spec turns decisions into a golden doc, cross-cutting concerns merge at planning time)\n - Do not prepend metadata to stored content (already in enum fields)\n\nAcceptance Criteria:\n- SKILL.md exists at skills/workflow-knowledge/SKILL.md\n- Documents both single and batch query invocation forms\n- Documents all query flags and their behaviour\n- Documents the exact output format with examples\n- Documents confidence tiers with guidance on how to weigh them\n- Documents the two-step retrieval pattern (query -\u003e read source file on demand)\n- Documents what NOT to do (spec exclusion, slug queries, speculative dumps)\n- Follows project skill file conventions from CLAUDE.md\n- Can be loaded by reference from Layer 2 files (Task 6-2)\n\nTests:\n- No automated tests — documentation task. Validation is manual:\n - Read the SKILL.md and verify it provides enough information to correctly construct and interpret knowledge queries\n - Verify it follows the project's skill file structure conventions\n\nEdge Cases:\n- The SKILL.md must describe BOTH hybrid and keyword-only modes without making keyword-only feel broken — it is a supported degraded mode\n- Must not duplicate the CLI help text verbatim — this is higher-level guidance about when and why, not just how\n- Must explain that --work-unit is a re-ranking hint, not a filter — this is a common misunderstanding that would produce wrong queries if not clear\n- Batch query section must explain deduplication and merged limit behaviour\n\nSpec Reference: knowledge-base/design.md — Three-layer integration pattern (lines 716-724, Layer 1 description), Retrieved Context Format (lines 576-605, exact output format), Confidence Tiers (lines 514-525), Two-step retrieval pattern (lines 735-737), Query construction (line 737), Batch query (line 602-603, merged and deduplicated), Specification excluded from automatic retrieval (line 560)","transitions":[{"from":"open","to":"in_progress","at":"2026-04-18T18:59:31Z","auto":false},{"from":"in_progress","to":"done","at":"2026-04-18T19:01:08Z","auto":false}],"parent":"tick-496c59","created":"2026-04-09T18:22:30Z","updated":"2026-04-18T19:01:08Z","closed":"2026-04-18T19:01:08Z"} {"id":"tick-c5a9f0","title":"Per-Phase Usage References + Contextual Query at Phase Start","status":"done","priority":2,"type":"task","refs":["knowledge-base-6-2"],"description":"Problem: Layer 1 (SKILL.md) documents the API, but Claude needs phase-specific guidance on WHEN to query and WHY — the trigger heuristics contextualised for each phase's work. Without Layer 2, Claude has the capability but not the judgment to use it effectively. Additionally, Claude needs explicit guidance on how to handle query failures — the design doc mandates pausing the workflow, not silently proceeding.\n\nSolution: Create usage reference files loaded early in processing skills that describe when and why to query during each specific phase, how to handle failures, plus the contextual query at phase start for research, discussion, and investigation.\n\nOutcome: Every processing skill loads phase-appropriate querying guidance early in its flow, the three early phases perform a contextual query at phase start, and query failures are handled by pausing with user options rather than silently skipping.\n\nDo:\n\nUSAGE REFERENCE FILES (Layer 2):\n- Create reference files — either one shared file or per-phase files, depending on how much the guidance differs between phases. The design doc (line 720) says: may be shared if guidance is generic enough, or local per phase if each needs different emphasis.\n- Recommended approach: one shared reference at skills/workflow-shared/references/knowledge-usage.md that covers the common trigger heuristics, with phase-specific notes where needed. This avoids maintaining 8 near-identical files.\n- Content:\n - Load the knowledge SKILL.md (Layer 1, Task 6-1) by reference for API details\n - Trigger heuristics — when to query (from design doc lines 551-557):\n 1. At topic boundaries — conversation edges toward adjacent territory\n 2. Upstream/downstream dependencies — current topic may affect or be affected by other work\n 3. Unfamiliar territory — not sure whether something was explored before\n 4. User prompts — user asks to check for prior context\n - Encourage proactive querying — under-querying is the bigger risk (design doc line 1003)\n - Multiple queries from different angles are expected and encouraged\n - Query construction: use natural language derived from what is currently being discussed, not topic names\n - Two-step retrieval reminder: query first (lightweight), read source file only when a chunk warrants investigation\n\nQUERY FAILURE HANDLING (from design doc lines 767-776):\n- This is skill-level behavior, not CLI behavior. The CLI retries 3 times and then exits with a non-zero code and error message (Task 4-4). The SKILL must handle what happens next:\n 1. If knowledge query fails (non-zero exit): PAUSE the workflow. Do not silently proceed without context.\n 2. Present the error clearly: what failed, likely causes (API key expired, network down, store corrupted).\n 3. Offer the user two options: fix the issue and retry, or explicitly choose to proceed without knowledge context.\n 4. If the user chooses to proceed: continue the phase but note that knowledge retrieval was skipped. This note should be visible in the output so the user knows context may be missing.\n- The design doc is emphatic: the value of the knowledge base is too high to silently skip (line 776).\n- This failure handling guidance goes in the usage reference (Layer 2) so it applies to all phases that load it.\n\n- Phase-specific notes within the shared reference (or in separate files if warranted):\n - Research: query at start + throughout. Early phase, high chance of overlap with prior work.\n - Discussion: query at start + throughout. Decisions being made that may relate to prior decisions.\n - Investigation: query at start + throughout. Symptoms and root causes may have been seen before.\n - Specification: EXCLUDED from automatic retrieval. Explicit note: do not query during spec authoring. Cross-cutting concerns merge at planning time, not spec time (design doc line 560).\n - Scoping: query throughout. Quick-fix scoping benefits from knowing if the issue was discussed elsewhere.\n - Planning: query throughout, especially for cross-cutting context. The explicit cross-cutting query is handled separately (Task 6-3).\n - Implementation: query when hitting unfamiliar territory or when a task touches areas covered by prior work.\n - Review: query to verify decisions against prior context.\n\nCONTEXTUAL QUERY AT PHASE START:\n- Add to the processing skills for research, discussion, and investigation: at the beginning of the phase (after loading references, before the first substantive step), construct a natural language query from available context and search the knowledge base.\n- Available context for query construction (from design doc line 549): topic description, bootstrap answers, handoff context, problem statement — whatever is available at that point.\n- NOT the topic slug. The query must be descriptive: not auth-flow but user authentication flow using OAuth2 with PKCE for mobile and web clients.\n- Returns a small, focused result set. Zero cost if nothing comes back. High value when it catches prior work.\n- This is a single query, not a dump. If results come back, Claude reads them and proceeds with that context. If nothing comes back, proceed as normal.\n- Specification is EXCLUDED — no contextual query at spec phase start.\n\nLOAD DIRECTIVES IN PROCESSING SKILLS:\n- Add a load directive for the usage reference early in each processing skill (alongside where case conventions are loaded). The exact insertion point varies per skill — read each to find the right place.\n- Processing skills that need this:\n skills/workflow-research-process/SKILL.md\n skills/workflow-discussion-process/SKILL.md\n skills/workflow-investigation-process/SKILL.md\n skills/workflow-scoping-process/SKILL.md\n skills/workflow-planning-process/SKILL.md\n skills/workflow-implementation-process/SKILL.md\n skills/workflow-review-process/SKILL.md\n- Specification process does NOT load the usage reference (excluded from automatic retrieval).\n\nALLOWED-TOOLS FOR REMAINING PROCESSING SKILLS:\n- Add Bash(node .claude/skills/workflow-knowledge/scripts/knowledge.cjs) to:\n skills/workflow-planning-process/SKILL.md\n skills/workflow-implementation-process/SKILL.md\n skills/workflow-review-process/SKILL.md\n- These 3 were deferred from Phase 5 — now they need it for autonomous querying.\n- Scoping process already has it from Phase 5 Task 5-2. Research, discussion, investigation, specification process already have it from Task 5-2.\n\nAcceptance Criteria:\n- Usage reference file(s) exist with trigger heuristics and phase-specific guidance\n- Usage reference loads Layer 1 (SKILL.md) by reference for API details\n- Query failure handling documented: pause workflow, present error, offer user choice to proceed or fix\n- All 7 processing skills (except specification) load the usage reference early in their flow\n- Specification process does NOT load the usage reference\n- Research, discussion, and investigation processing skills perform a contextual query at phase start\n- Contextual query uses descriptive natural language, not topic slugs\n- allowed-tools added to planning, implementation, and review processing skills\n- Trigger heuristics match the design doc (topic boundaries, dependencies, unfamiliar territory, user prompts)\n\nTests:\n- No automated tests — skill file editing task. Validation is manual:\n - Start a discussion in a test project with existing indexed knowledge -\u003e verify contextual query runs and surfaces relevant prior work\n - Start a specification -\u003e verify no contextual query runs\n - Simulate query failure -\u003e verify workflow pauses with user options (not silent skip)\n - Verify all processing skills load the usage reference\n\nEdge Cases:\n- Contextual query with no prior knowledge indexed — returns [0 results], phase proceeds normally with no delay or noise\n- Phase start with very little context available (e.g., just a topic name) — construct the best query possible from what is available. A poor query that returns nothing is fine. The design doc accepts zero cost if nothing comes back.\n- Query failure during contextual query at phase start — same failure handling applies (pause, present, offer choice). The contextual query is not exempt from failure handling.\n- Shared vs per-phase reference: if a shared reference becomes unwieldy with too many phase-specific notes, split into per-phase files. Start shared, split if needed.\n\nSpec Reference: knowledge-base/design.md — Three-layer integration pattern (lines 716-724, Layer 2 description), Autonomous querying trigger heuristics (lines 551-557), Contextual query at phase start (line 549), Specification excluded (line 560), Query Failures section (lines 767-776, pause workflow, present error, user choice), Autonomous query guardrails review finding #16 (line 1002)","transitions":[{"from":"open","to":"in_progress","at":"2026-04-18T19:01:23Z","auto":false},{"from":"in_progress","to":"done","at":"2026-04-18T19:10:11Z","auto":false}],"parent":"tick-496c59","created":"2026-04-09T18:23:15Z","updated":"2026-04-18T19:10:11Z","closed":"2026-04-18T19:10:11Z"} -{"id":"tick-2841d6","title":"Inline Callouts + Planning Entry Cross-Cutting Query","status":"open","priority":2,"type":"task","refs":["knowledge-base-6-3"],"description":"Problem: Layer 2 provides general guidance loaded once at the start of a phase, but Claude can lose awareness of the knowledge base as a conversation develops. Layer 3 addresses this with targeted nudges at specific moments where querying is most valuable. Additionally, the planning entry skill has an existing manual approach for cross-cutting context that should be replaced with a targeted semantic query.\n\nSolution: Add inline callouts at pertinent points in processing skills and replace the planning entry cross-cutting context approach with a knowledge base query.\n\nOutcome: Claude gets timely reminders to check the knowledge base at high-value moments, and planning entry uses semantic search instead of manually reading every cross-cutting spec.\n\nDo:\n\nINLINE CALLOUTS (Layer 3):\n- Add brief reminders within the step flow of processing skills at moments where the knowledge base is most valuable. These are nudges, not full reference loads — same pattern as existing callouts for review agents and commit reminders (design doc line 722).\n- Format: a short inline note like: Consider querying the knowledge base — this subtopic may have been explored in prior work. Or: If this constraint seems familiar, check the knowledge base for prior decisions.\n- Placement is judgment-based — read each processing skill and identify moments where:\n - A complex subtopic is being explored\n - A decision is being made that could conflict with prior work\n - An assumption is being introduced that may have been validated or rejected before\n - The conversation moves to adjacent territory\n- Processing skills to add callouts to (all except specification):\n skills/workflow-research-process/SKILL.md — when exploring new directions, before concluding\n skills/workflow-discussion-process/SKILL.md — when discussing options, before deciding\n skills/workflow-investigation-process/SKILL.md — when analysing root causes\n skills/workflow-scoping-process/SKILL.md — when scoping constraints\n skills/workflow-planning-process/SKILL.md — when designing phases/tasks that touch other areas\n skills/workflow-implementation-process/SKILL.md — when hitting unfamiliar code areas\n skills/workflow-review-process/SKILL.md — when verifying decisions against original intent\n- These are 1-2 line callouts embedded at specific step boundaries, NOT new steps or reference loads. They should feel natural, not interruptive.\n- Do NOT add callouts to the specification process — specification is excluded from automatic retrieval.\n\nPLANNING ENTRY CROSS-CUTTING QUERY:\n- This replaces existing functionality in skills/workflow-planning-entry/references/cross-cutting-context.md (design doc line 562).\n- The current approach: reads every cross-cutting specification and manually assesses relevance to the current topic. This is expensive (loads all cross-cutting specs into context) and keyword-dependent (misses semantic connections).\n- The replacement: a targeted semantic query filtered to work_type: cross-cutting.\n node .claude/skills/workflow-knowledge/scripts/knowledge.cjs query \u003ctopic_description\u003e --work-type cross-cutting --limit 10\n- The query term should be constructed from the current topic's specification summary or description — not the topic name.\n- Results are cross-cutting specs that are semantically relevant to the current plan. Claude reads the results, identifies applicable cross-cutting decisions, and incorporates them into the planning context.\n- This is a deterministic step replacing existing functionality, not a speculative search (design doc line 726).\n- Update or replace cross-cutting-context.md to use the knowledge query instead of manual spec reading.\n- Ensure skills/workflow-planning-entry/SKILL.md has allowed-tools for knowledge.cjs if not already present (it may have been added as an entry-point skill in Task 5-1, but planning-entry is a phase entry skill, not an entry-point skill — check).\n\nAcceptance Criteria:\n- Inline callouts exist at pertinent points in 7 processing skills (all except specification)\n- Callouts are brief nudges (1-2 lines), not full reference loads\n- Callouts are placed at high-value moments identified by reading each skill's flow\n- Specification process has NO callouts\n- Planning entry cross-cutting query replaces the manual approach in cross-cutting-context.md\n- Cross-cutting query uses --work-type cross-cutting filter\n- Cross-cutting query uses descriptive topic text, not topic slug\n- Planning entry has allowed-tools for knowledge.cjs\n\nTests:\n- No automated tests — skill file editing task. Validation is manual:\n - Read processing skills and verify callouts are placed at high-value moments\n - Start planning for a topic with existing cross-cutting specs indexed -\u003e verify the query surfaces relevant cross-cutting decisions\n - Verify the old manual cross-cutting spec reading approach is replaced, not duplicated\n\nEdge Cases:\n- Planning entry cross-cutting query when no cross-cutting specs are indexed — returns [0 results], planning proceeds without cross-cutting context (same as today when no cross-cutting specs exist)\n- Callout placement in skills with varying step structures — read each skill carefully, do not add callouts at the same structural position in every skill. Placement is semantic, not mechanical.\n- The planning-entry skill is a phase entry skill (internal, user-invocable: false), not an entry-point skill. It was NOT updated in Task 5-1 (which targeted start-*/continue-* skills). It needs allowed-tools for the cross-cutting query added here.\n\nSpec Reference: knowledge-base/design.md — Three-layer integration pattern (lines 716-724, Layer 3 description — inline callouts same pattern as review agents and commit reminders), Planning entry cross-cutting query (line 562, replaces existing manual approach, filtered to work_type: cross-cutting), and the note that this is a deterministic step replacing existing functionality (line 726)","parent":"tick-496c59","created":"2026-04-09T18:23:50Z","updated":"2026-04-09T18:23:50Z"} +{"id":"tick-2841d6","title":"Inline Callouts + Planning Entry Cross-Cutting Query","status":"done","priority":2,"type":"task","refs":["knowledge-base-6-3"],"description":"Problem: Layer 2 provides general guidance loaded once at the start of a phase, but Claude can lose awareness of the knowledge base as a conversation develops. Layer 3 addresses this with targeted nudges at specific moments where querying is most valuable. Additionally, the planning entry skill has an existing manual approach for cross-cutting context that should be replaced with a targeted semantic query.\n\nSolution: Add inline callouts at pertinent points in processing skills and replace the planning entry cross-cutting context approach with a knowledge base query.\n\nOutcome: Claude gets timely reminders to check the knowledge base at high-value moments, and planning entry uses semantic search instead of manually reading every cross-cutting spec.\n\nDo:\n\nINLINE CALLOUTS (Layer 3):\n- Add brief reminders within the step flow of processing skills at moments where the knowledge base is most valuable. These are nudges, not full reference loads — same pattern as existing callouts for review agents and commit reminders (design doc line 722).\n- Format: a short inline note like: Consider querying the knowledge base — this subtopic may have been explored in prior work. Or: If this constraint seems familiar, check the knowledge base for prior decisions.\n- Placement is judgment-based — read each processing skill and identify moments where:\n - A complex subtopic is being explored\n - A decision is being made that could conflict with prior work\n - An assumption is being introduced that may have been validated or rejected before\n - The conversation moves to adjacent territory\n- Processing skills to add callouts to (all except specification):\n skills/workflow-research-process/SKILL.md — when exploring new directions, before concluding\n skills/workflow-discussion-process/SKILL.md — when discussing options, before deciding\n skills/workflow-investigation-process/SKILL.md — when analysing root causes\n skills/workflow-scoping-process/SKILL.md — when scoping constraints\n skills/workflow-planning-process/SKILL.md — when designing phases/tasks that touch other areas\n skills/workflow-implementation-process/SKILL.md — when hitting unfamiliar code areas\n skills/workflow-review-process/SKILL.md — when verifying decisions against original intent\n- These are 1-2 line callouts embedded at specific step boundaries, NOT new steps or reference loads. They should feel natural, not interruptive.\n- Do NOT add callouts to the specification process — specification is excluded from automatic retrieval.\n\nPLANNING ENTRY CROSS-CUTTING QUERY:\n- This replaces existing functionality in skills/workflow-planning-entry/references/cross-cutting-context.md (design doc line 562).\n- The current approach: reads every cross-cutting specification and manually assesses relevance to the current topic. This is expensive (loads all cross-cutting specs into context) and keyword-dependent (misses semantic connections).\n- The replacement: a targeted semantic query filtered to work_type: cross-cutting.\n node .claude/skills/workflow-knowledge/scripts/knowledge.cjs query \u003ctopic_description\u003e --work-type cross-cutting --limit 10\n- The query term should be constructed from the current topic's specification summary or description — not the topic name.\n- Results are cross-cutting specs that are semantically relevant to the current plan. Claude reads the results, identifies applicable cross-cutting decisions, and incorporates them into the planning context.\n- This is a deterministic step replacing existing functionality, not a speculative search (design doc line 726).\n- Update or replace cross-cutting-context.md to use the knowledge query instead of manual spec reading.\n- Ensure skills/workflow-planning-entry/SKILL.md has allowed-tools for knowledge.cjs if not already present (it may have been added as an entry-point skill in Task 5-1, but planning-entry is a phase entry skill, not an entry-point skill — check).\n\nAcceptance Criteria:\n- Inline callouts exist at pertinent points in 7 processing skills (all except specification)\n- Callouts are brief nudges (1-2 lines), not full reference loads\n- Callouts are placed at high-value moments identified by reading each skill's flow\n- Specification process has NO callouts\n- Planning entry cross-cutting query replaces the manual approach in cross-cutting-context.md\n- Cross-cutting query uses --work-type cross-cutting filter\n- Cross-cutting query uses descriptive topic text, not topic slug\n- Planning entry has allowed-tools for knowledge.cjs\n\nTests:\n- No automated tests — skill file editing task. Validation is manual:\n - Read processing skills and verify callouts are placed at high-value moments\n - Start planning for a topic with existing cross-cutting specs indexed -\u003e verify the query surfaces relevant cross-cutting decisions\n - Verify the old manual cross-cutting spec reading approach is replaced, not duplicated\n\nEdge Cases:\n- Planning entry cross-cutting query when no cross-cutting specs are indexed — returns [0 results], planning proceeds without cross-cutting context (same as today when no cross-cutting specs exist)\n- Callout placement in skills with varying step structures — read each skill carefully, do not add callouts at the same structural position in every skill. Placement is semantic, not mechanical.\n- The planning-entry skill is a phase entry skill (internal, user-invocable: false), not an entry-point skill. It was NOT updated in Task 5-1 (which targeted start-*/continue-* skills). It needs allowed-tools for the cross-cutting query added here.\n\nSpec Reference: knowledge-base/design.md — Three-layer integration pattern (lines 716-724, Layer 3 description — inline callouts same pattern as review agents and commit reminders), Planning entry cross-cutting query (line 562, replaces existing manual approach, filtered to work_type: cross-cutting), and the note that this is a deterministic step replacing existing functionality (line 726)","transitions":[{"from":"open","to":"in_progress","at":"2026-04-18T19:10:26Z","auto":false},{"from":"in_progress","to":"done","at":"2026-04-18T19:13:35Z","auto":false}],"parent":"tick-496c59","created":"2026-04-09T18:23:50Z","updated":"2026-04-18T19:13:35Z","closed":"2026-04-18T19:13:35Z"} {"id":"tick-2e511f","title":"Phase 7: Setup Wizard","status":"open","priority":2,"refs":["knowledge-base-7"],"parent":"tick-cbbd13","created":"2026-04-09T19:04:09Z","updated":"2026-04-09T19:04:09Z"} {"id":"tick-78c1c7","title":"Setup Wizard: System Config + Project Init + Stub Mode","status":"open","priority":2,"type":"task","refs":["knowledge-base-7-1"],"description":"Problem: Users need a single entry point to configure the knowledge base for the first time. This involves system-level configuration (API keys, provider choice) that lives in the user's home directory and project-level initialisation that lives in .workflows/. Both must be handled in one flow so the user doesn't need to know the internal structure.\n\nSolution: Implement the knowledge setup command as an interactive wizard using Node's readline interface, handling system config, project init, and stub mode in one guided flow.\n\nOutcome: A user can run one command and have a fully configured knowledge base ready for use, with clear prompts at each step and graceful handling of partial or existing configuration.\n\nDo:\n- Implement the setup command handler in the CLI (invoked by Task 3-1 dispatch).\n- Invocation: knowledge setup (no arguments)\n- HUMAN-ONLY — uses interactive prompts throughout via Node readline interface (process.stdin/process.stdout). Claude cannot handle interactive terminals — this is the natural protection against accidental invocation (design doc line 632).\n\nSTEP 1: SYSTEM CONFIG (~/.config/workflows/config.json):\n- Check if system config already exists.\n - If it exists: read it, display current settings, ask if the user wants to reconfigure or skip. If skip, proceed to Step 2.\n - If it does not exist: create ~/.config/workflows/ directory if needed.\n- Prompt for provider:\n Which embedding provider? (openai / skip)\n - openai: proceed with OpenAI configuration\n - skip: stub mode (keyword-only search, no embeddings). Write config with no provider field. Display clear message about limitations. Proceed to Step 2.\n- If openai selected:\n - Prompt for model (default: text-embedding-3-small):\n Embedding model [text-embedding-3-small]:\n - Prompt for dimensions (default: 1536):\n Vector dimensions [1536]:\n - Prompt for API key env var name (default: OPENAI_API_KEY):\n API key environment variable [OPENAI_API_KEY]:\n - Check if the env var is set in the current environment:\n - If set: validate with a test embed call — embed a short test string and verify a vector is returned. If validation fails, display the error and ask the user to fix it or continue anyway.\n - If not set: warn the user and explain they need to set this env var in their shell profile before using the knowledge base. Do not block — they may be setting it up for later.\n- Write system config to ~/.config/workflows/config.json:\n { knowledge: { provider, model, dimensions, api_key_env, similarity_threshold: 0.8, decay_months: 6 } }\n- For stub mode (skip): write minimal config:\n { knowledge: { similarity_threshold: 0.8, decay_months: 6 } }\n\nSTEP 2: PROJECT INIT (.workflows/.knowledge/):\n- Check if project knowledge base directory already exists with config.json and store.msp.\n - If fully initialised: display status and ask to skip or reinitialise. If skip, proceed to Step 3.\n - If partially initialised (directory exists but missing files): complete the missing pieces.\n - If not initialised: create from scratch.\n- Create .workflows/.knowledge/ directory.\n- Write .workflows/.knowledge/config.json — project-level config. By default this is empty (inherits everything from system config):\n { knowledge: {} }\n The user can customise project-level overrides later by editing this file.\n- Create an empty Orama store and save it to .workflows/.knowledge/store.msp using createStore + saveStore from Phase 1. Use the dimensions from the resolved config (system + project merge).\n- Write .workflows/.knowledge/metadata.json with the provider/model/dimensions from the resolved config (or empty provider fields for stub mode).\n\nREADLINE INTERFACE:\n- Use Node built-in readline module (require('readline')).\n- Create interface with input: process.stdin, output: process.stdout.\n- Use rl.question() for prompts with defaults shown in brackets.\n- Close the interface when done.\n- If stdin is not a TTY (piped input, non-interactive environment): detect with process.stdin.isTTY and abort with message: knowledge setup requires an interactive terminal. Run it directly, not through Claude.\n\nAcceptance Criteria:\n- knowledge setup prompts for provider, model, dimensions, API key env var\n- System config is written to ~/.config/workflows/config.json\n- Project knowledge base is initialised at .workflows/.knowledge/ with config.json, store.msp, metadata.json\n- Test embed call validates the API key when configured\n- Stub mode writes config without provider, displays limitation message\n- Existing system config is detected and can be skipped or reconfigured\n- Existing project init is detected and can be skipped\n- Non-interactive terminal is detected and aborts with clear message\n- npm run build succeeds with the setup command included\n\nTests:\n- No automated tests for the interactive flow — it is inherently human-driven.\n- Unit tests for the non-interactive parts (tests/scripts/test-knowledge-config.cjs — extend from Task 3-1):\n - it creates a valid system config object from provider choices\n - it creates a valid stub-mode config object\n - it detects existing system config correctly\n - it detects existing project init correctly\n - it creates the project directory structure correctly\n\nEdge Cases:\n- ~/.config/workflows/ directory does not exist — create it (mkdir -p equivalent with { recursive: true })\n- .workflows/ directory does not exist — this means no workflow project exists. Display error: No .workflows/ directory found. Initialise a workflow project first.\n- System config file exists but is invalid JSON — display error, offer to overwrite\n- API key env var is set but the test embed call fails (wrong key, network error) — display error, offer to continue setup anyway (user may fix the key later)\n- User presses Ctrl+C during setup — readline handles SIGINT, process exits cleanly\n- Previous setup was stub mode, user re-runs with openai — detect existing store has no vectors, suggest knowledge rebuild after setup completes\n\nSpec Reference: knowledge-base/design.md — knowledge setup command (lines 626-633, interactive wizard flow, skip logic, stub mode), System config creation flow review finding #18 (line 1008), Configuration Hierarchy section (lines 258-301, system and project config schemas)","parent":"tick-2e511f","created":"2026-04-09T19:05:02Z","updated":"2026-04-09T19:05:02Z"} {"id":"tick-b4348b","title":"Setup Wizard: Initial Indexing + Idempotency + CLI Integration","status":"open","priority":2,"type":"task","refs":["knowledge-base-7-2"],"description":"Problem: After system config and project init (Task 7-1), the knowledge base is empty. Existing projects may have dozens of completed artifacts that need to be indexed. The setup wizard must automatically index everything as its final step, and re-running setup must be safe — skipping already-completed steps without duplicating work.\n\nSolution: Wire up the existing bulk index logic (Task 4-4) as the final step of the setup wizard, ensure the full setup flow is idempotent, and register setup in the CLI dispatch.\n\nOutcome: Running knowledge setup on a project with existing completed work populates the knowledge base immediately. Re-running setup on an already-configured project skips to indexing (or exits if everything is done).\n\nDo:\n\nINITIAL INDEXING (Step 3 of the setup wizard):\n- After system config (Step 1) and project init (Step 2) complete (or are skipped), run initial indexing.\n- This delegates to the existing knowledge index (no args) bulk index logic from Task 4-4.\n- The bulk index discovers all completed artifacts via manifest, diffs against the store (which is empty for first setup), and indexes everything.\n- Display progress as files are indexed (same output as the bulk index command).\n- Display a clear completion summary covering how many files and chunks were indexed.\n- If the store already has chunks (re-run scenario): the bulk index logic naturally skips already-indexed items and only processes missing ones. No special handling needed.\n- If indexing fails for some files: the retry/pending queue mechanism from Task 4-4 handles it. Inform the user that some files could not be indexed and were added to the pending queue for automatic retry on next use.\n\nIDEMPOTENCY:\n- The full setup flow must be safe to re-run at any point:\n - System config exists → display current settings, offer to skip or reconfigure\n - Project init exists → display status, offer to skip or reinitialise\n - Store has chunks → bulk index skips already-indexed, only processes new/missing\n - Everything is current → display a clear \"already set up\" message and exit.\n- This covers the design doc requirement (line 631): skips steps that are already done.\n- Also covers the interrupted-setup scenario (design doc finding #5, line 965): if setup was interrupted mid-indexing, re-running picks up where it left off via the pending queue.\n\nCLI INTEGRATION:\n- Register the setup command in the CLI dispatch from Task 3-1. Task 3-1 lists setup alongside other Phase 4+ commands with a \"not yet implemented\" placeholder — replace that placeholder with a real handler that calls the wizard flow from Task 7-1 followed by the initial indexing from this task.\n\nSTUB-TO-FULL UPGRADE PATH:\n- If the user previously ran setup in stub mode and now re-runs with an OpenAI provider:\n - System config is updated with the new provider settings.\n - The existing store has no vectors (keyword-only mode).\n - Inform the user that the previous setup was keyword-only and they should run knowledge rebuild to re-index with embeddings for full hybrid search.\n - Do NOT automatically rebuild — it is destructive and may take time. The user should run it explicitly.\n- This matches the design doc (line 329): upgrading from stub to full requires knowledge rebuild.\n\nAcceptance Criteria:\n- Setup wizard indexes all existing completed artifacts as its final step\n- Progress and summary output matches the bulk index command\n- Failed indexing files are logged to pending queue with a note to the user\n- Re-running setup on a fully configured project exits cleanly with an already-set-up message\n- Re-running setup after interrupted indexing picks up where it left off\n- Setup command registered in CLI dispatch, replacing the Task 3-1 not-yet-implemented placeholder\n- Stub-to-full upgrade detected and user informed about knowledge rebuild\n- npm run build succeeds\n\nTests:\n- Unit tests for idempotency logic (tests/scripts/test-knowledge-config.cjs — extend):\n - it detects fully configured state (system + project + indexed)\n - it detects partially configured state (system exists, project missing)\n - it detects empty store needing initial indexing\n- CLI dispatch test (tests/scripts/test-knowledge-cli.sh — extend):\n - it routes to setup command without error (non-interactive detection will abort, which is the expected behaviour in test)\n- Manual validation:\n - Run setup on a project with existing completed artifacts -\u003e verify all are indexed\n - Run setup again -\u003e verify it skips everything and exits cleanly\n - Run setup after interruption -\u003e verify pending queue items are processed\n\nEdge Cases:\n- Project with no completed work units — initial indexing indexes 0 files, which is correct. The knowledge base is ready but empty.\n- Project with hundreds of completed artifacts — initial indexing may take time (embedding API calls). Display progress so the user knows it is working.\n- Setup interrupted with Ctrl+C during indexing — indexed files are saved (each save is atomic), unindexed files go to pending queue. Re-run picks up.\n- System config points to a provider but the API key env var is not set — initial indexing will fail (provider cannot embed). The retry/pending queue catches this. Setup still completes — the project is initialised, indexing is pending.\n- Multiple projects sharing the same system config — this is normal. System config has provider/key, each project has its own .workflows/.knowledge/. Setup only modifies the current project.\n\nSpec Reference: knowledge-base/design.md — knowledge setup command (lines 626-633, initial indexing as final step, skip logic), Init/resumability finding #5 (line 965, interrupted setup, pending queue picks up), Upgrading from stub to full (line 329, requires rebuild)","parent":"tick-2e511f","created":"2026-04-09T19:05:40Z","updated":"2026-04-10T20:47:17Z"} diff --git a/skills/workflow-discussion-process/SKILL.md b/skills/workflow-discussion-process/SKILL.md index c5316ad4..d4444ba3 100644 --- a/skills/workflow-discussion-process/SKILL.md +++ b/skills/workflow-discussion-process/SKILL.md @@ -186,6 +186,8 @@ Load **[contextual-query.md](../workflow-shared/references/contextual-query.md)* Load **[discussion-session.md](references/discussion-session.md)** and follow its instructions as written. +*Knowledge-base nudge — before committing to a direction on a new subtopic, or when a decision might echo one made elsewhere, run a quick query. See **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)**.* + → Proceed to **Step 6**. --- diff --git a/skills/workflow-implementation-process/SKILL.md b/skills/workflow-implementation-process/SKILL.md index 7e350945..4ac4f175 100644 --- a/skills/workflow-implementation-process/SKILL.md +++ b/skills/workflow-implementation-process/SKILL.md @@ -234,6 +234,8 @@ Load **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)** Load **[task-loop.md](references/task-loop.md)** and follow its instructions as written. +*Knowledge-base nudge — when a task enters unfamiliar code or touches an area covered by prior work, query the knowledge base to check assumptions before writing code. See **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)**.* + After the loop completes: #### If the task loop exited early (user chose `stop`) diff --git a/skills/workflow-investigation-process/SKILL.md b/skills/workflow-investigation-process/SKILL.md index 582ef29f..edb87f9e 100644 --- a/skills/workflow-investigation-process/SKILL.md +++ b/skills/workflow-investigation-process/SKILL.md @@ -242,6 +242,8 @@ Synthesize findings into a clear root cause: Document in the investigation file and commit. +*Knowledge-base nudge — if the root cause pattern feels familiar, query the knowledge base before moving on. A matching prior investigation can confirm the diagnosis or surface a related bug. See **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)**.* + → Proceed to **Step 7**. --- diff --git a/skills/workflow-planning-entry/SKILL.md b/skills/workflow-planning-entry/SKILL.md index 385bb4e1..c7d71e0a 100644 --- a/skills/workflow-planning-entry/SKILL.md +++ b/skills/workflow-planning-entry/SKILL.md @@ -1,7 +1,7 @@ --- name: workflow-planning-entry user-invocable: false -allowed-tools: Bash(node .claude/skills/workflow-manifest/scripts/manifest.cjs) +allowed-tools: Bash(node .claude/skills/workflow-manifest/scripts/manifest.cjs), Bash(node .claude/skills/workflow-knowledge/scripts/knowledge.cjs) --- Act as **precise intake coordinator**. Follow each step literally without interpretation. Do not engage with the subject matter — your role is preparation, not processing. diff --git a/skills/workflow-planning-entry/references/cross-cutting-context.md b/skills/workflow-planning-entry/references/cross-cutting-context.md index 04e257db..a990ebf8 100644 --- a/skills/workflow-planning-entry/references/cross-cutting-context.md +++ b/skills/workflow-planning-entry/references/cross-cutting-context.md @@ -4,9 +4,21 @@ --- -Surface completed cross-cutting specifications as context for planning. Applies to ALL work types. +Surface cross-cutting specifications as context for planning. Applies to ALL work types. -## A. Discover Cross-Cutting Work Units +Previously this loaded every completed cross-cutting spec into context and manually assessed relevance. It now issues a semantic query filtered to `work_type: cross-cutting` so only specs that are semantically relevant to the current plan surface. In-progress cross-cutting work is still called out explicitly — a semantic query can't see unfinished specs, and the user needs that awareness before planning around assumptions that might change. + +## A. Build the query text + +Read the current topic's specification at `.workflows/{work_unit}/specification/{topic}/specification.md`. Extract a short natural-language description of the feature — the opening summary, the problem statement, or the first substantive paragraph after the frontmatter. Aim for 1-3 sentences that describe *what the plan is about*. + +Do not use the topic slug as the query term — slugs are weak semantic signal. If the spec is unusually terse and yields no natural description, construct a descriptive phrase from the spec's headings. + +Store the resulting text as `{query_text}`. + +## B. Flag in-progress cross-cutting specs + +A semantic query only surfaces completed work. An in-progress cross-cutting spec may contain decisions that will bind this plan but aren't yet indexed — the user needs to be aware. ```bash node .claude/skills/workflow-manifest/scripts/manifest.cjs project list --type cross-cutting @@ -14,29 +26,25 @@ node .claude/skills/workflow-manifest/scripts/manifest.cjs project list --type c #### If no output (no cross-cutting work units exist) -→ Return to caller. +→ Proceed to **C. Query the knowledge base**. #### If cross-cutting work units found -Store the list of names. For each, check specification status: +For each name, check specification status: ```bash node .claude/skills/workflow-manifest/scripts/manifest.cjs get {cc_work_unit}.specification.{cc_work_unit} status ``` -Collect only those with `status: completed`. Also note any with `status: in-progress`. - -→ Proceed to **B. Assess Relevance**. +Collect work units whose spec status is `in-progress`. -## B. Assess Relevance +#### If no in-progress specs -#### If no completed cross-cutting specifications exist and no in-progress ones are relevant - -→ Return to caller. +→ Proceed to **C. Query the knowledge base**. -#### If in-progress cross-cutting specs exist +#### If in-progress specs exist -Assess relevance of each in-progress spec to the feature being planned (by topic overlap — e.g., a caching strategy is relevant if the feature involves data retrieval or API calls). +Assess relevance of each in-progress spec to the feature being planned (by topic overlap — a caching strategy is relevant if the feature involves data retrieval or API calls). **If relevant in-progress specs exist:** @@ -46,7 +54,7 @@ Assess relevance of each in-progress spec to the feature being planned (by topic Cross-cutting specifications still in progress: These may contain architectural decisions relevant to this plan. - • {topic} + • {cc_work_unit} ``` > *Output the next fenced block as markdown (not a code block):* @@ -68,37 +76,45 @@ Proceed without these, or complete them first? **If user chose `c`/`continue`:** -→ Proceed to **C. Summarize Completed**. +→ Proceed to **C. Query the knowledge base**. -#### Otherwise +**If no in-progress specs are relevant:** -→ Proceed to **C. Summarize Completed**. +→ Proceed to **C. Query the knowledge base**. -## C. Summarize Completed +## C. Query the knowledge base -#### If no completed cross-cutting specifications exist +Run a targeted semantic query filtered to completed cross-cutting specs: + +```bash +node .claude/skills/workflow-knowledge/scripts/knowledge.cjs query "{query_text}" --work-type cross-cutting --phase specification --limit 10 +``` + +#### If the command exits with a non-zero code + +→ Load **[knowledge-usage.md](../../workflow-shared/references/knowledge-usage.md)** for **D. Query failure handling** and follow its instructions. + +#### If stdout is `[0 results]` + +No cross-cutting specs are semantically relevant to this plan. Proceed without cross-cutting context. → Return to caller. -#### If completed cross-cutting specifications exist +#### If results are returned -For each completed cross-cutting spec, read the specification file at `.workflows/{cc_work_unit}/specification/{cc_work_unit}/specification.md` to build a brief summary. Assess relevance to the feature being planned. +Read the returned chunks. Group by work unit — each unique `work_unit/topic` in the provenance lines represents one cross-cutting spec. For each, if the chunks alone are not enough to judge relevance, read the source file (`Source:` line) for full detail. -**If relevant completed specs exist:** +Keep only the specs that are genuinely relevant to the plan being built. A chunk matching on generic vocabulary (e.g., both mention "authentication") but addressing unrelated concerns should be dropped. > *Output the next fenced block as a code block:* ``` Cross-cutting specifications to reference: - • {topic}: {brief summary of key decisions} + • {cc_work_unit}: {brief summary of key decisions relevant to this plan} ``` -These specifications contain validated architectural decisions that should inform the plan. The planning skill will incorporate these as a "Cross-Cutting References" section in the plan. - -Store confirmed specs for handoff to planning process. - -→ Return to caller. +These specifications contain validated architectural decisions that should inform the plan. The planning skill will incorporate them as a "Cross-Cutting References" section in the plan. -**If no completed specs are relevant:** +Store the confirmed cross-cutting specs (work unit name and source file path) for handoff to the planning process. → Return to caller. diff --git a/skills/workflow-planning-process/SKILL.md b/skills/workflow-planning-process/SKILL.md index 433f1bea..2cf4e1f5 100644 --- a/skills/workflow-planning-process/SKILL.md +++ b/skills/workflow-planning-process/SKILL.md @@ -264,6 +264,8 @@ Load **[verify-source-material.md](references/verify-source-material.md)** and f Load **[plan-construction.md](references/plan-construction.md)** and follow its instructions as written. +*Knowledge-base nudge — when designing phases or tasks that touch adjacent areas, query the knowledge base for prior architectural decisions. Cross-cutting context was surfaced at planning entry; use autonomous querying for anything else. See **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)**.* + → Proceed to **Step 7**. --- diff --git a/skills/workflow-research-process/SKILL.md b/skills/workflow-research-process/SKILL.md index 24f65958..ce6695dc 100644 --- a/skills/workflow-research-process/SKILL.md +++ b/skills/workflow-research-process/SKILL.md @@ -208,3 +208,5 @@ Load **[contextual-query.md](../workflow-shared/references/contextual-query.md)* ``` Load **[route-session.md](references/route-session.md)** and follow its instructions as written. + +*Knowledge-base nudge — if a thread feels familiar, or you're about to re-tread ground that might have been covered in another work unit, run a quick query before proceeding. See **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)**.* diff --git a/skills/workflow-review-process/SKILL.md b/skills/workflow-review-process/SKILL.md index 45766b60..c69784e9 100644 --- a/skills/workflow-review-process/SKILL.md +++ b/skills/workflow-review-process/SKILL.md @@ -280,6 +280,8 @@ Load **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)** Load **[invoke-task-verifiers.md](references/invoke-task-verifiers.md)** and follow its instructions as written. +*Knowledge-base nudge — when a decision in the implementation looks inconsistent with how similar decisions were made elsewhere, query the knowledge base to verify before flagging it. See **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)**.* + → Proceed to **Step 6**. --- diff --git a/skills/workflow-scoping-process/SKILL.md b/skills/workflow-scoping-process/SKILL.md index 2845476d..af819a75 100644 --- a/skills/workflow-scoping-process/SKILL.md +++ b/skills/workflow-scoping-process/SKILL.md @@ -139,6 +139,8 @@ Load **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)** Load **[gather-context.md](references/gather-context.md)** and follow its instructions as written. +*Knowledge-base nudge — if the change touches an area with prior discussions, investigations, or specs, query the knowledge base while gathering context. A "mechanical change" often has a history. See **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)**.* + → Proceed to **Step 3**. --- From fa29b65951ed72f36891e31c665a9bab3cb2b2b5 Mon Sep 17 00:00:00 2001 From: Lee Overy Date: Sun, 19 Apr 2026 11:34:20 +0100 Subject: [PATCH 4/9] refactor(knowledge): colocate knowledge references under workflow-knowledge MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Moves knowledge-check, reindex-work-unit, knowledge-usage, and contextual-query from skills/workflow-shared/references/ into skills/workflow-knowledge/references/ so the knowledge skill owns its domain references. workflow-shared/references/ now holds only truly cross-domain protocols (casing, compliance, background-agents, natural-breaks, convergence). Updates all 22 caller Load directives and attribution headers. No behavioural changes — structural reorganisation only. Co-Authored-By: Claude Opus 4.7 (1M context) --- skills/continue-bugfix/SKILL.md | 2 +- skills/continue-cross-cutting/SKILL.md | 2 +- skills/continue-epic/SKILL.md | 2 +- skills/continue-feature/SKILL.md | 2 +- skills/continue-quickfix/SKILL.md | 2 +- skills/start-bugfix/SKILL.md | 2 +- skills/start-cross-cutting/SKILL.md | 2 +- skills/start-epic/SKILL.md | 2 +- skills/start-feature/SKILL.md | 2 +- skills/start-quickfix/SKILL.md | 2 +- skills/workflow-discussion-process/SKILL.md | 6 +++--- skills/workflow-implementation-process/SKILL.md | 4 ++-- skills/workflow-investigation-process/SKILL.md | 6 +++--- .../references/contextual-query.md | 2 +- .../references/knowledge-check.md | 2 +- .../references/knowledge-usage.md | 4 ++-- .../references/reindex-work-unit.md | 2 +- .../references/cross-cutting-context.md | 2 +- skills/workflow-planning-process/SKILL.md | 4 ++-- skills/workflow-research-process/SKILL.md | 6 +++--- skills/workflow-review-process/SKILL.md | 4 ++-- skills/workflow-scoping-process/SKILL.md | 4 ++-- skills/workflow-start/SKILL.md | 2 +- skills/workflow-start/references/manage-work-unit.md | 2 +- skills/workflow-start/references/view-completed.md | 2 +- 25 files changed, 36 insertions(+), 36 deletions(-) rename skills/{workflow-shared => workflow-knowledge}/references/contextual-query.md (95%) rename skills/{workflow-shared => workflow-knowledge}/references/knowledge-check.md (96%) rename skills/{workflow-shared => workflow-knowledge}/references/knowledge-usage.md (95%) rename skills/{workflow-shared => workflow-knowledge}/references/reindex-work-unit.md (89%) diff --git a/skills/continue-bugfix/SKILL.md b/skills/continue-bugfix/SKILL.md index 36fd9935..237dd8f7 100644 --- a/skills/continue-bugfix/SKILL.md +++ b/skills/continue-bugfix/SKILL.md @@ -66,7 +66,7 @@ Invoke the `/workflow-migrate` skill and follow its instructions exactly — if ### Step 0.3: Knowledge Check -Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. +Load **[knowledge-check.md](../workflow-knowledge/references/knowledge-check.md)** and follow its instructions as written. → Proceed to **Step 1**. diff --git a/skills/continue-cross-cutting/SKILL.md b/skills/continue-cross-cutting/SKILL.md index f63a7344..1c061257 100644 --- a/skills/continue-cross-cutting/SKILL.md +++ b/skills/continue-cross-cutting/SKILL.md @@ -66,7 +66,7 @@ Invoke the `/workflow-migrate` skill and follow its instructions exactly — if ### Step 0.3: Knowledge Check -Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. +Load **[knowledge-check.md](../workflow-knowledge/references/knowledge-check.md)** and follow its instructions as written. → Proceed to **Step 1**. diff --git a/skills/continue-epic/SKILL.md b/skills/continue-epic/SKILL.md index 69114bb0..8cfc09a4 100644 --- a/skills/continue-epic/SKILL.md +++ b/skills/continue-epic/SKILL.md @@ -66,7 +66,7 @@ Invoke the `/workflow-migrate` skill and follow its instructions exactly — if ### Step 0.3: Knowledge Check -Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. +Load **[knowledge-check.md](../workflow-knowledge/references/knowledge-check.md)** and follow its instructions as written. → Proceed to **Step 1**. diff --git a/skills/continue-feature/SKILL.md b/skills/continue-feature/SKILL.md index f1d90c16..c16e559e 100644 --- a/skills/continue-feature/SKILL.md +++ b/skills/continue-feature/SKILL.md @@ -66,7 +66,7 @@ Invoke the `/workflow-migrate` skill and follow its instructions exactly — if ### Step 0.3: Knowledge Check -Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. +Load **[knowledge-check.md](../workflow-knowledge/references/knowledge-check.md)** and follow its instructions as written. → Proceed to **Step 1**. diff --git a/skills/continue-quickfix/SKILL.md b/skills/continue-quickfix/SKILL.md index b8a1e8c9..514cbe65 100644 --- a/skills/continue-quickfix/SKILL.md +++ b/skills/continue-quickfix/SKILL.md @@ -66,7 +66,7 @@ Invoke the `/workflow-migrate` skill and follow its instructions exactly — if ### Step 0.3: Knowledge Check -Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. +Load **[knowledge-check.md](../workflow-knowledge/references/knowledge-check.md)** and follow its instructions as written. → Proceed to **Step 1**. diff --git a/skills/start-bugfix/SKILL.md b/skills/start-bugfix/SKILL.md index f253440d..3fd96b8c 100644 --- a/skills/start-bugfix/SKILL.md +++ b/skills/start-bugfix/SKILL.md @@ -73,7 +73,7 @@ Invoke the `/workflow-migrate` skill and follow its instructions exactly — if > then hand off to investigation to diagnose the root cause. ``` -Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. +Load **[knowledge-check.md](../workflow-knowledge/references/knowledge-check.md)** and follow its instructions as written. → Proceed to **Step 1**. diff --git a/skills/start-cross-cutting/SKILL.md b/skills/start-cross-cutting/SKILL.md index 36be54e1..8000103a 100644 --- a/skills/start-cross-cutting/SKILL.md +++ b/skills/start-cross-cutting/SKILL.md @@ -75,7 +75,7 @@ Invoke the `/workflow-migrate` skill and follow its instructions exactly — if > pipeline ends at specification — no planning or implementation. ``` -Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. +Load **[knowledge-check.md](../workflow-knowledge/references/knowledge-check.md)** and follow its instructions as written. → Proceed to **Step 1**. diff --git a/skills/start-epic/SKILL.md b/skills/start-epic/SKILL.md index d1dda6e4..c7d3b928 100644 --- a/skills/start-epic/SKILL.md +++ b/skills/start-epic/SKILL.md @@ -74,7 +74,7 @@ Invoke the `/workflow-migrate` skill and follow its instructions exactly — if > straight to discussion. ``` -Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. +Load **[knowledge-check.md](../workflow-knowledge/references/knowledge-check.md)** and follow its instructions as written. → Proceed to **Step 1**. diff --git a/skills/start-feature/SKILL.md b/skills/start-feature/SKILL.md index 55a58f1a..db229a63 100644 --- a/skills/start-feature/SKILL.md +++ b/skills/start-feature/SKILL.md @@ -74,7 +74,7 @@ Invoke the `/workflow-migrate` skill and follow its instructions exactly — if > to discussion. ``` -Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. +Load **[knowledge-check.md](../workflow-knowledge/references/knowledge-check.md)** and follow its instructions as written. → Proceed to **Step 1**. diff --git a/skills/start-quickfix/SKILL.md b/skills/start-quickfix/SKILL.md index af7dc59a..e2ffa6b9 100644 --- a/skills/start-quickfix/SKILL.md +++ b/skills/start-quickfix/SKILL.md @@ -74,7 +74,7 @@ Invoke the `/workflow-migrate` skill and follow its instructions exactly — if > and plan into a single streamlined pass. ``` -Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. +Load **[knowledge-check.md](../workflow-knowledge/references/knowledge-check.md)** and follow its instructions as written. → Proceed to **Step 1**. diff --git a/skills/workflow-discussion-process/SKILL.md b/skills/workflow-discussion-process/SKILL.md index d4444ba3..9b666fd9 100644 --- a/skills/workflow-discussion-process/SKILL.md +++ b/skills/workflow-discussion-process/SKILL.md @@ -141,7 +141,7 @@ Load **[discussion-guidelines.md](references/discussion-guidelines.md)** and fol > proactive querying is available throughout the discussion. ``` -Load **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)** and follow its instructions as written. +Load **[knowledge-usage.md](../workflow-knowledge/references/knowledge-usage.md)** and follow its instructions as written. → Proceed to **Step 4**. @@ -162,7 +162,7 @@ Load **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)** > to this discussion topic before the session begins. ``` -Load **[contextual-query.md](../workflow-shared/references/contextual-query.md)** and follow its instructions as written. +Load **[contextual-query.md](../workflow-knowledge/references/contextual-query.md)** and follow its instructions as written. → Proceed to **Step 5**. @@ -186,7 +186,7 @@ Load **[contextual-query.md](../workflow-shared/references/contextual-query.md)* Load **[discussion-session.md](references/discussion-session.md)** and follow its instructions as written. -*Knowledge-base nudge — before committing to a direction on a new subtopic, or when a decision might echo one made elsewhere, run a quick query. See **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)**.* +*Knowledge-base nudge — before committing to a direction on a new subtopic, or when a decision might echo one made elsewhere, run a quick query. See **[knowledge-usage.md](../workflow-knowledge/references/knowledge-usage.md)**.* → Proceed to **Step 6**. diff --git a/skills/workflow-implementation-process/SKILL.md b/skills/workflow-implementation-process/SKILL.md index 4ac4f175..bcd52d24 100644 --- a/skills/workflow-implementation-process/SKILL.md +++ b/skills/workflow-implementation-process/SKILL.md @@ -210,7 +210,7 @@ Load **[linter-setup.md](references/linter-setup.md)** and follow its instructio > proactive querying is available while tasks execute. ``` -Load **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)** and follow its instructions as written. +Load **[knowledge-usage.md](../workflow-knowledge/references/knowledge-usage.md)** and follow its instructions as written. → Proceed to **Step 7**. @@ -234,7 +234,7 @@ Load **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)** Load **[task-loop.md](references/task-loop.md)** and follow its instructions as written. -*Knowledge-base nudge — when a task enters unfamiliar code or touches an area covered by prior work, query the knowledge base to check assumptions before writing code. See **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)**.* +*Knowledge-base nudge — when a task enters unfamiliar code or touches an area covered by prior work, query the knowledge base to check assumptions before writing code. See **[knowledge-usage.md](../workflow-knowledge/references/knowledge-usage.md)**.* After the loop completes: diff --git a/skills/workflow-investigation-process/SKILL.md b/skills/workflow-investigation-process/SKILL.md index edb87f9e..968c04a0 100644 --- a/skills/workflow-investigation-process/SKILL.md +++ b/skills/workflow-investigation-process/SKILL.md @@ -143,7 +143,7 @@ Load **[initialize-investigation.md](references/initialize-investigation.md)** a > proactive querying is available throughout the investigation. ``` -Load **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)** and follow its instructions as written. +Load **[knowledge-usage.md](../workflow-knowledge/references/knowledge-usage.md)** and follow its instructions as written. → Proceed to **Step 3**. @@ -189,7 +189,7 @@ When symptoms are sufficiently understood to begin code analysis: > related work that matches the symptoms just gathered. ``` -Load **[contextual-query.md](../workflow-shared/references/contextual-query.md)** and follow its instructions as written. +Load **[contextual-query.md](../workflow-knowledge/references/contextual-query.md)** and follow its instructions as written. → Proceed to **Step 5**. @@ -242,7 +242,7 @@ Synthesize findings into a clear root cause: Document in the investigation file and commit. -*Knowledge-base nudge — if the root cause pattern feels familiar, query the knowledge base before moving on. A matching prior investigation can confirm the diagnosis or surface a related bug. See **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)**.* +*Knowledge-base nudge — if the root cause pattern feels familiar, query the knowledge base before moving on. A matching prior investigation can confirm the diagnosis or surface a related bug. See **[knowledge-usage.md](../workflow-knowledge/references/knowledge-usage.md)**.* → Proceed to **Step 7**. diff --git a/skills/workflow-shared/references/contextual-query.md b/skills/workflow-knowledge/references/contextual-query.md similarity index 95% rename from skills/workflow-shared/references/contextual-query.md rename to skills/workflow-knowledge/references/contextual-query.md index a27c7319..9de959d6 100644 --- a/skills/workflow-shared/references/contextual-query.md +++ b/skills/workflow-knowledge/references/contextual-query.md @@ -1,6 +1,6 @@ # Contextual Query -*Shared reference for research, discussion, and investigation processing skills.* +*Reference for **[workflow-knowledge](../SKILL.md)** — loaded at phase start in research, discussion, and investigation processing skills.* --- diff --git a/skills/workflow-shared/references/knowledge-check.md b/skills/workflow-knowledge/references/knowledge-check.md similarity index 96% rename from skills/workflow-shared/references/knowledge-check.md rename to skills/workflow-knowledge/references/knowledge-check.md index 9351ded2..9150b0dd 100644 --- a/skills/workflow-shared/references/knowledge-check.md +++ b/skills/workflow-knowledge/references/knowledge-check.md @@ -1,6 +1,6 @@ # Knowledge Check -*Shared reference for all entry-point skills.* +*Reference for **[workflow-knowledge](../SKILL.md)** — loaded by all entry-point skills in Step 0.* --- diff --git a/skills/workflow-shared/references/knowledge-usage.md b/skills/workflow-knowledge/references/knowledge-usage.md similarity index 95% rename from skills/workflow-shared/references/knowledge-usage.md rename to skills/workflow-knowledge/references/knowledge-usage.md index 08d0faf0..1f618717 100644 --- a/skills/workflow-shared/references/knowledge-usage.md +++ b/skills/workflow-knowledge/references/knowledge-usage.md @@ -1,12 +1,12 @@ # Knowledge Usage -*Shared reference for processing skills (research, discussion, investigation, scoping, planning, implementation, review).* +*Reference for **[workflow-knowledge](../SKILL.md)** — loaded by processing skills (research, discussion, investigation, scoping, planning, implementation, review).* --- This reference sets expectations for how you use the knowledge base *during* a phase — when to query, how to construct queries, how to interpret results, and what to do if a query fails. Load it early in the phase so the guidance is active from the first substantive step. -For API details (commands, flags, output format, confidence tiers, two-step retrieval), load **[SKILL.md](../../workflow-knowledge/SKILL.md)** — the knowledge skill's API documentation. +For API details (commands, flags, output format, confidence tiers, two-step retrieval), load **[SKILL.md](../SKILL.md)** — the knowledge skill's API documentation. --- diff --git a/skills/workflow-shared/references/reindex-work-unit.md b/skills/workflow-knowledge/references/reindex-work-unit.md similarity index 89% rename from skills/workflow-shared/references/reindex-work-unit.md rename to skills/workflow-knowledge/references/reindex-work-unit.md index 9484a896..0226a75e 100644 --- a/skills/workflow-shared/references/reindex-work-unit.md +++ b/skills/workflow-knowledge/references/reindex-work-unit.md @@ -1,6 +1,6 @@ # Re-Index Work Unit -*Shared reference for skills that need to re-index all completed artifacts of a work unit (e.g., reactivation after cancellation, feature-to-epic pivot).* +*Reference for **[workflow-knowledge](../SKILL.md)** — loaded by skills that need to re-index all completed artifacts of a work unit (e.g., reactivation after cancellation, feature-to-epic pivot).* --- diff --git a/skills/workflow-planning-entry/references/cross-cutting-context.md b/skills/workflow-planning-entry/references/cross-cutting-context.md index a990ebf8..1e3ebc04 100644 --- a/skills/workflow-planning-entry/references/cross-cutting-context.md +++ b/skills/workflow-planning-entry/references/cross-cutting-context.md @@ -92,7 +92,7 @@ node .claude/skills/workflow-knowledge/scripts/knowledge.cjs query "{query_text} #### If the command exits with a non-zero code -→ Load **[knowledge-usage.md](../../workflow-shared/references/knowledge-usage.md)** for **D. Query failure handling** and follow its instructions. +→ Load **[knowledge-usage.md](../../workflow-knowledge/references/knowledge-usage.md)** for **D. Query failure handling** and follow its instructions. #### If stdout is `[0 results]` diff --git a/skills/workflow-planning-process/SKILL.md b/skills/workflow-planning-process/SKILL.md index 2cf4e1f5..2407b887 100644 --- a/skills/workflow-planning-process/SKILL.md +++ b/skills/workflow-planning-process/SKILL.md @@ -219,7 +219,7 @@ Load **[planning-principles.md](references/planning-principles.md)** and follow > proactive querying is available while planning tasks. ``` -Load **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)** and follow its instructions as written. +Load **[knowledge-usage.md](../workflow-knowledge/references/knowledge-usage.md)** and follow its instructions as written. → Proceed to **Step 5**. @@ -264,7 +264,7 @@ Load **[verify-source-material.md](references/verify-source-material.md)** and f Load **[plan-construction.md](references/plan-construction.md)** and follow its instructions as written. -*Knowledge-base nudge — when designing phases or tasks that touch adjacent areas, query the knowledge base for prior architectural decisions. Cross-cutting context was surfaced at planning entry; use autonomous querying for anything else. See **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)**.* +*Knowledge-base nudge — when designing phases or tasks that touch adjacent areas, query the knowledge base for prior architectural decisions. Cross-cutting context was surfaced at planning entry; use autonomous querying for anything else. See **[knowledge-usage.md](../workflow-knowledge/references/knowledge-usage.md)**.* → Proceed to **Step 7**. diff --git a/skills/workflow-research-process/SKILL.md b/skills/workflow-research-process/SKILL.md index ce6695dc..5544e7af 100644 --- a/skills/workflow-research-process/SKILL.md +++ b/skills/workflow-research-process/SKILL.md @@ -164,7 +164,7 @@ Load **[research-guidelines.md](references/research-guidelines.md)** and follow > proactive querying is available throughout the phase. ``` -Load **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)** and follow its instructions as written. +Load **[knowledge-usage.md](../workflow-knowledge/references/knowledge-usage.md)** and follow its instructions as written. → Proceed to **Step 5**. @@ -185,7 +185,7 @@ Load **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)** > to this research topic before the session begins. ``` -Load **[contextual-query.md](../workflow-shared/references/contextual-query.md)** and follow its instructions as written. +Load **[contextual-query.md](../workflow-knowledge/references/contextual-query.md)** and follow its instructions as written. → Proceed to **Step 6**. @@ -209,4 +209,4 @@ Load **[contextual-query.md](../workflow-shared/references/contextual-query.md)* Load **[route-session.md](references/route-session.md)** and follow its instructions as written. -*Knowledge-base nudge — if a thread feels familiar, or you're about to re-tread ground that might have been covered in another work unit, run a quick query before proceeding. See **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)**.* +*Knowledge-base nudge — if a thread feels familiar, or you're about to re-tread ground that might have been covered in another work unit, run a quick query before proceeding. See **[knowledge-usage.md](../workflow-knowledge/references/knowledge-usage.md)**.* diff --git a/skills/workflow-review-process/SKILL.md b/skills/workflow-review-process/SKILL.md index c69784e9..302d468f 100644 --- a/skills/workflow-review-process/SKILL.md +++ b/skills/workflow-review-process/SKILL.md @@ -256,7 +256,7 @@ Load **[load-project-skills.md](references/load-project-skills.md)** and follow > proactive querying is available while verifying decisions. ``` -Load **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)** and follow its instructions as written. +Load **[knowledge-usage.md](../workflow-knowledge/references/knowledge-usage.md)** and follow its instructions as written. → Proceed to **Step 5**. @@ -280,7 +280,7 @@ Load **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)** Load **[invoke-task-verifiers.md](references/invoke-task-verifiers.md)** and follow its instructions as written. -*Knowledge-base nudge — when a decision in the implementation looks inconsistent with how similar decisions were made elsewhere, query the knowledge base to verify before flagging it. See **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)**.* +*Knowledge-base nudge — when a decision in the implementation looks inconsistent with how similar decisions were made elsewhere, query the knowledge base to verify before flagging it. See **[knowledge-usage.md](../workflow-knowledge/references/knowledge-usage.md)**.* → Proceed to **Step 6**. diff --git a/skills/workflow-scoping-process/SKILL.md b/skills/workflow-scoping-process/SKILL.md index af819a75..246b484f 100644 --- a/skills/workflow-scoping-process/SKILL.md +++ b/skills/workflow-scoping-process/SKILL.md @@ -116,7 +116,7 @@ node .claude/skills/workflow-manifest/scripts/manifest.cjs set {work_unit}.scopi > proactive querying is available while scoping the change. ``` -Load **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)** and follow its instructions as written. +Load **[knowledge-usage.md](../workflow-knowledge/references/knowledge-usage.md)** and follow its instructions as written. → Proceed to **Step 2**. @@ -139,7 +139,7 @@ Load **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)** Load **[gather-context.md](references/gather-context.md)** and follow its instructions as written. -*Knowledge-base nudge — if the change touches an area with prior discussions, investigations, or specs, query the knowledge base while gathering context. A "mechanical change" often has a history. See **[knowledge-usage.md](../workflow-shared/references/knowledge-usage.md)**.* +*Knowledge-base nudge — if the change touches an area with prior discussions, investigations, or specs, query the knowledge base while gathering context. A "mechanical change" often has a history. See **[knowledge-usage.md](../workflow-knowledge/references/knowledge-usage.md)**.* → Proceed to **Step 3**. diff --git a/skills/workflow-start/SKILL.md b/skills/workflow-start/SKILL.md index 9da2450a..67db7e08 100644 --- a/skills/workflow-start/SKILL.md +++ b/skills/workflow-start/SKILL.md @@ -73,7 +73,7 @@ Invoke the `/workflow-migrate` skill and follow its instructions exactly — if ### Step 0.3: Knowledge Check -Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. +Load **[knowledge-check.md](../workflow-knowledge/references/knowledge-check.md)** and follow its instructions as written. → Proceed to **Step 1**. diff --git a/skills/workflow-start/references/manage-work-unit.md b/skills/workflow-start/references/manage-work-unit.md index 729b89d4..5abc1dd1 100644 --- a/skills/workflow-start/references/manage-work-unit.md +++ b/skills/workflow-start/references/manage-work-unit.md @@ -205,7 +205,7 @@ node .claude/skills/workflow-manifest/scripts/manifest.cjs set {selected.name} w Re-index all completed artifacts so their chunks carry the new `work_type: epic`: -Load **[reindex-work-unit.md](../workflow-shared/references/reindex-work-unit.md)** with work_unit = `{selected.name}`. +Load **[reindex-work-unit.md](../../workflow-knowledge/references/reindex-work-unit.md)** with work_unit = `{selected.name}`. > *Output the next fenced block as markdown (not a code block):* diff --git a/skills/workflow-start/references/view-completed.md b/skills/workflow-start/references/view-completed.md index 37471ad1..b9acc9b0 100644 --- a/skills/workflow-start/references/view-completed.md +++ b/skills/workflow-start/references/view-completed.md @@ -102,7 +102,7 @@ node .claude/skills/workflow-manifest/scripts/manifest.cjs set {selected.name} s **If `selected.status` was `cancelled`:** -Cancellation removed the work unit's chunks from the knowledge base. Restore them by loading **[reindex-work-unit.md](../workflow-shared/references/reindex-work-unit.md)** with work_unit = `{selected.name}`. +Cancellation removed the work unit's chunks from the knowledge base. Restore them by loading **[reindex-work-unit.md](../../workflow-knowledge/references/reindex-work-unit.md)** with work_unit = `{selected.name}`. > *Output the next fenced block as a code block:* From 2a9254f04f6c5b46e2a167ecc016385a01097dd6 Mon Sep 17 00:00:00 2001 From: Lee Overy Date: Sun, 19 Apr 2026 11:37:36 +0100 Subject: [PATCH 5/9] refactor(knowledge): deduplicate query guidance across reference files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit SKILL.md is now the single source for query construction examples and two-step retrieval. knowledge-usage.md keeps the context-level principles (short) and points to SKILL.md for examples and the flag table. contextual-query.md defers to knowledge-usage.md B for construction rules (same deferral pattern it already uses for D failure handling). No behavioural change — removes verbatim duplication so future guidance updates land in one place. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../references/contextual-query.md | 4 +--- .../references/knowledge-usage.md | 18 +++--------------- 2 files changed, 4 insertions(+), 18 deletions(-) diff --git a/skills/workflow-knowledge/references/contextual-query.md b/skills/workflow-knowledge/references/contextual-query.md index 9de959d6..6ba344f1 100644 --- a/skills/workflow-knowledge/references/contextual-query.md +++ b/skills/workflow-knowledge/references/contextual-query.md @@ -12,9 +12,7 @@ This is **not** a speculative dump. It is a focused check using the best context Build a short natural-language description of what this phase is about using whatever context you have at hand: the topic description, the handoff context, bootstrap answers already captured, the problem statement, and — for investigation — the initial symptoms. -- **Do** describe the thing in the language the original author would have used. -- **Do not** use the topic slug. `"auth-flow"` is a weak semantic signal; `"user authentication flow using OAuth2 with PKCE for mobile and web clients"` is strong. -- **Do** run a batch query (multiple angles) if you have several distinct framings — one for the feature, one for the constraint, one for the suspected dependency. Batch queries are a single CLI call. +Follow the construction rules in **[knowledge-usage.md](knowledge-usage.md)** — **B. How to construct queries** (natural language, not slugs; batch for multiple angles). If you have several distinct framings, batch them in one call. If the only context available is a topic name, construct the best descriptive query you can. A poor query that returns nothing is acceptable — the cost is one store load. diff --git a/skills/workflow-knowledge/references/knowledge-usage.md b/skills/workflow-knowledge/references/knowledge-usage.md index 1f618717..c620b5ef 100644 --- a/skills/workflow-knowledge/references/knowledge-usage.md +++ b/skills/workflow-knowledge/references/knowledge-usage.md @@ -25,25 +25,13 @@ Multiple queries from different angles are expected and encouraged. One query fo ## B. How to construct queries -Use **natural language** describing what you're looking for. Not topic slugs — slugs are weak semantic signal. A query should read like a sentence the original author would have written. +Use **natural language** describing what you're looking for — not topic slugs, which are weak semantic signal. Filter with `--work-type`, `--phase`, `--topic`; bias toward the current work unit with `--work-unit` (a re-rank hint, not a filter). For multiple angles in one invocation, pass multiple positional terms (batch query). -- Good: `"OAuth2 PKCE flow for mobile clients"` -- Good: `"why we ruled out email as a primary identity field"` -- Poor: `"auth-flow"` (slug, weak signal) -- Poor: `"auth"` (too broad) - -Use the CLI flags to filter, not the query string: - -- `--work-type ` — filter to a work type (hard filter) -- `--phase ` — filter to a phase (hard filter) -- `--topic ` — filter to a topic (hard filter) -- `--work-unit ` — **re-ranking hint, not a filter** — boosts results from the current work unit while still returning cross-work-unit context - -For batch queries (multiple angles in one invocation), pass multiple positional terms. See the knowledge skill for details. +See **[SKILL.md](../SKILL.md)** — query construction examples and the full flag table. ## C. Two-step retrieval -Results include chunks with provenance. Don't read source files for every chunk — read only when a chunk looks load-bearing for what you're doing. The chunk text alone is usually enough to judge relevance; the source file is there for deep dives. +Chunks land in context; read the source file (from the `Source:` line) only when a chunk looks load-bearing. See **[SKILL.md](../SKILL.md)** — two-step retrieval pattern. ## D. Query failure handling From da17f95291419d9f93a2985aa65d5df13f1af729 Mon Sep 17 00:00:00 2001 From: Lee Overy Date: Sun, 19 Apr 2026 12:22:51 +0100 Subject: [PATCH 6/9] fix(knowledge): tighten routing in failure-handling branches MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - knowledge-usage.md D: both retry/skip branches now end with explicit → Return to caller - contextual-query.md B: adds explicit routing for both non-zero and exit-0 branches, with post-D skip vs retry-succeeded sub-routing - cross-cutting-context.md B: restructures in-progress sub-branches to use bold nested conditionals with explicit Proceed/Return routing - cross-cutting-context.md C: adds post-D routing (skip vs retry) so every branch is self-contained per CLAUDE.md convention No behavioural change — makes the control flow explicit where it previously relied on implicit fall-through. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../references/contextual-query.md | 9 ++++++++- .../references/knowledge-usage.md | 8 ++++++-- .../references/cross-cutting-context.md | 17 ++++++----------- 3 files changed, 20 insertions(+), 14 deletions(-) diff --git a/skills/workflow-knowledge/references/contextual-query.md b/skills/workflow-knowledge/references/contextual-query.md index 6ba344f1..3389a9e7 100644 --- a/skills/workflow-knowledge/references/contextual-query.md +++ b/skills/workflow-knowledge/references/contextual-query.md @@ -26,7 +26,14 @@ node .claude/skills/workflow-knowledge/scripts/knowledge.cjs query " *Output the next fenced block as a code block:* @@ -78,10 +74,6 @@ Proceed without these, or complete them first? → Proceed to **C. Query the knowledge base**. -**If no in-progress specs are relevant:** - -→ Proceed to **C. Query the knowledge base**. - ## C. Query the knowledge base Run a targeted semantic query filtered to completed cross-cutting specs: @@ -92,7 +84,10 @@ node .claude/skills/workflow-knowledge/scripts/knowledge.cjs query "{query_text} #### If the command exits with a non-zero code -→ Load **[knowledge-usage.md](../../workflow-knowledge/references/knowledge-usage.md)** for **D. Query failure handling** and follow its instructions. +Load **[knowledge-usage.md](../../workflow-knowledge/references/knowledge-usage.md)** for **D. Query failure handling** and follow its instructions. When D returns: + +- **If the user chose `skip`** — → Return to caller (plan proceeds without cross-cutting context). +- **If a retry succeeded** — re-evaluate stdout using the `[0 results]` or results-returned branches below. #### If stdout is `[0 results]` From 80ccd5e0cef8cc7eb8c90432b402bf31f7a1f1ac Mon Sep 17 00:00:00 2001 From: Lee Overy Date: Sun, 19 Apr 2026 12:31:23 +0100 Subject: [PATCH 7/9] fix(research): correct narrative in final-review.md for terminal Step 6 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Research Step 6 is terminal (Research Session) — there is no backbone step after it. The "returns to the backbone to proceed toward conclusion" phrasing was copy-pasted from discussion's final-review.md where Step 6 IS a backbone step with Step 7+ after. Narrative now describes the actual control flow: return to topic-completion which runs document review, compliance, and the conclude menu. Co-Authored-By: Claude Opus 4.7 (1M context) --- skills/workflow-research-process/references/final-review.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/workflow-research-process/references/final-review.md b/skills/workflow-research-process/references/final-review.md index 0b8ae77e..d0b7265e 100644 --- a/skills/workflow-research-process/references/final-review.md +++ b/skills/workflow-research-process/references/final-review.md @@ -6,7 +6,7 @@ A final review ensures the research is thorough before moving to discussion. Even if review agents ran during the session, the research may have progressed significantly since the last one. -This step runs once per "user signals done" entry. It dispatches a fresh review if needed, raises one finding via the shared protocol, then bounces back to the research session so the user can engage naturally. The next time the user signals done, Step 6 re-runs — eventually all findings are drained and the file transitions to `incorporated`, at which point Step 6 returns to the backbone to proceed toward conclusion. +This flow runs once per "user signals done" entry during Step 6 (Research Session). It dispatches a fresh review if needed, raises one finding via the shared protocol, then bounces back to the research session so the user can engage naturally. The next time the user signals done, this flow re-runs — eventually all findings are drained and the file transitions to `incorporated`, at which point control returns to topic-completion so the phase can proceed through document review, compliance, and the conclude menu. The **never-dump rules apply in full**. Findings are raised one at a time via the shared surfacing protocol. From 14dda380566a970c9698c9c79a75d8929466bf75 Mon Sep 17 00:00:00 2001 From: Lee Overy Date: Sun, 19 Apr 2026 16:46:36 +0100 Subject: [PATCH 8/9] refactor(knowledge): narrow KB guidance for planning, implementation, review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Planning-time KB queries create an escape hatch that undermines the spec's golden-doc status. The pipeline already captures context via discussion → spec; spec gaps are blockers, not KB-fill opportunities. - knowledge-usage.md E: - Planning: do not query. Spec is golden; gaps go back to the user. Cross-cutting stays at entry only (existing mechanism). - Implementation: code is source of truth for *what*; KB is only for *why* context behind existing patterns (rare). - Review: cross-work-unit consistency checks only. - planning SKILL.md: remove inline callout (encouraged anti-pattern). - implementation SKILL.md: narrow inline callout to why-only usage. - review SKILL.md: narrow inline callout to cross-work-unit checks. Research, discussion, investigation, scoping callouts unchanged — autonomous querying is legitimate there (exploring, deciding, diagnosing). Co-Authored-By: Claude Opus 4.7 (1M context) --- skills/workflow-implementation-process/SKILL.md | 2 +- skills/workflow-knowledge/references/knowledge-usage.md | 6 +++--- skills/workflow-planning-process/SKILL.md | 2 -- skills/workflow-review-process/SKILL.md | 2 +- 4 files changed, 5 insertions(+), 7 deletions(-) diff --git a/skills/workflow-implementation-process/SKILL.md b/skills/workflow-implementation-process/SKILL.md index bcd52d24..16cc9b17 100644 --- a/skills/workflow-implementation-process/SKILL.md +++ b/skills/workflow-implementation-process/SKILL.md @@ -234,7 +234,7 @@ Load **[knowledge-usage.md](../workflow-knowledge/references/knowledge-usage.md) Load **[task-loop.md](references/task-loop.md)** and follow its instructions as written. -*Knowledge-base nudge — when a task enters unfamiliar code or touches an area covered by prior work, query the knowledge base to check assumptions before writing code. See **[knowledge-usage.md](../workflow-knowledge/references/knowledge-usage.md)**.* +*Knowledge-base nudge — code is the source of truth for *what* exists; read it rather than query. Reach for the KB only when you need the *why* behind an existing pattern (rare). Never to fill spec gaps — those are blockers. See **[knowledge-usage.md](../workflow-knowledge/references/knowledge-usage.md)**.* After the loop completes: diff --git a/skills/workflow-knowledge/references/knowledge-usage.md b/skills/workflow-knowledge/references/knowledge-usage.md index 3158bfdb..ede87d3c 100644 --- a/skills/workflow-knowledge/references/knowledge-usage.md +++ b/skills/workflow-knowledge/references/knowledge-usage.md @@ -84,8 +84,8 @@ Note in the current phase's working file that the knowledge query was skipped. E - **Investigation** — query at the start (after initial symptoms are gathered) and throughout. Symptoms and root causes may have been seen before — a matching prior investigation can save hours. - **Specification** — **do not query during this phase.** The spec turns discussion decisions into a golden document. Cross-cutting concerns merge at planning time via an explicit cross-cutting query, not during spec authoring. Querying mid-spec pulls the document away from its own source material. - **Scoping** — query throughout. Quick-fix scoping benefits from knowing if the issue was discussed or investigated elsewhere — a "mechanical change" often has a history. -- **Planning** — query throughout, especially when designing phases and tasks. Cross-cutting context is handled explicitly at planning entry (a targeted `--work-type cross-cutting` query replaces the old manual approach) — don't duplicate that work here. -- **Implementation** — query when a task touches unfamiliar territory or intersects with areas covered by prior work. Use it to check assumptions before writing code, not to retro-justify decisions after. -- **Review** — query to verify decisions against prior context. When something in the implementation looks inconsistent with how similar decisions were made elsewhere, the knowledge base is the quickest way to check. +- **Planning** — **do not query during planning.** The spec is the golden document; planning operates on the spec alone. If a spec gap surfaces during planning, flag it to the user — don't fill it with a KB query. Cross-cutting context is handled at planning entry via the explicit `--work-type cross-cutting` query (existing mechanism, not discretionary). +- **Implementation** — code is the source of truth for *what* exists during implementation. Read the code; don't query the KB for it. The KB is useful only for the *why* behind an existing pattern or decision (e.g., "why does this use UUID v7?" — the rationale lives in spec/discussion, not the code). Rare in practice. Never use it to fill spec gaps — those are blockers. +- **Review** — query only for cross-work-unit consistency checks ("does this mirror how similar decisions were made elsewhere?"). Consistency with the current spec is already in scope — no KB needed for that. → Return to caller. diff --git a/skills/workflow-planning-process/SKILL.md b/skills/workflow-planning-process/SKILL.md index 2407b887..9fa6f68f 100644 --- a/skills/workflow-planning-process/SKILL.md +++ b/skills/workflow-planning-process/SKILL.md @@ -264,8 +264,6 @@ Load **[verify-source-material.md](references/verify-source-material.md)** and f Load **[plan-construction.md](references/plan-construction.md)** and follow its instructions as written. -*Knowledge-base nudge — when designing phases or tasks that touch adjacent areas, query the knowledge base for prior architectural decisions. Cross-cutting context was surfaced at planning entry; use autonomous querying for anything else. See **[knowledge-usage.md](../workflow-knowledge/references/knowledge-usage.md)**.* - → Proceed to **Step 7**. --- diff --git a/skills/workflow-review-process/SKILL.md b/skills/workflow-review-process/SKILL.md index 302d468f..44a2ec9b 100644 --- a/skills/workflow-review-process/SKILL.md +++ b/skills/workflow-review-process/SKILL.md @@ -280,7 +280,7 @@ Load **[knowledge-usage.md](../workflow-knowledge/references/knowledge-usage.md) Load **[invoke-task-verifiers.md](references/invoke-task-verifiers.md)** and follow its instructions as written. -*Knowledge-base nudge — when a decision in the implementation looks inconsistent with how similar decisions were made elsewhere, query the knowledge base to verify before flagging it. See **[knowledge-usage.md](../workflow-knowledge/references/knowledge-usage.md)**.* +*Knowledge-base nudge — use only for cross-work-unit consistency checks ("does this mirror how similar decisions were made elsewhere?"). Consistency with the current spec is already in scope — no KB needed. See **[knowledge-usage.md](../workflow-knowledge/references/knowledge-usage.md)**.* → Proceed to **Step 6**. From 9cd63dda690f8d3926a302722cc3a376f4d245bb Mon Sep 17 00:00:00 2001 From: Lee Overy Date: Sun, 19 Apr 2026 17:15:40 +0100 Subject: [PATCH 9/9] docs(knowledge): remove historical note from cross-cutting-context The "previously this loaded every spec..." paragraph documented what the file used to do, not what it does. Rot magnet. Replaced with a description of current behaviour only. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../workflow-planning-entry/references/cross-cutting-context.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/workflow-planning-entry/references/cross-cutting-context.md b/skills/workflow-planning-entry/references/cross-cutting-context.md index b895b5a2..19242206 100644 --- a/skills/workflow-planning-entry/references/cross-cutting-context.md +++ b/skills/workflow-planning-entry/references/cross-cutting-context.md @@ -6,7 +6,7 @@ Surface cross-cutting specifications as context for planning. Applies to ALL work types. -Previously this loaded every completed cross-cutting spec into context and manually assessed relevance. It now issues a semantic query filtered to `work_type: cross-cutting` so only specs that are semantically relevant to the current plan surface. In-progress cross-cutting work is still called out explicitly — a semantic query can't see unfinished specs, and the user needs that awareness before planning around assumptions that might change. +Issue a semantic query filtered to `work_type: cross-cutting` so only specs relevant to the current plan surface. In-progress cross-cutting work is called out separately — a semantic query can't see unfinished specs, and the user needs that awareness before planning around assumptions that might change. ## A. Build the query text