@leeovery/claude-technical-workflows 2.1.17 → 2.1.19

package/skills/start-specification/references/analysis-flow.md

@@ -0,0 +1,103 @@
+# Analysis Flow
+
+*Reference for **[start-specification](../SKILL.md)***
+
+---
+
+## A. Gather Analysis Context
+
+```
+Before analyzing, is there anything about how these discussions relate
+that would help me group them appropriately?
+
+For example:
+- Topics that are part of the same feature
+- Dependencies between topics
+- Topics that must stay separate
+
+Your context (or 'none'):
+```
+
+**STOP.** Wait for user response. Note their input for the analysis.
+
+→ Proceed to **B. Analyze Discussions**.
+
+---
+
+## B. Analyze Discussions
+
+**This step is critical. You MUST read every concluded discussion document thoroughly.**
+
+For each concluded discussion:
+1. Read the ENTIRE document using the Read tool (not just frontmatter)
+2. Understand the decisions, systems, and concepts it defines
+3. Note dependencies on or references to other discussions
+4. Identify shared data structures, entities, or behaviors
+
+Then analyze coupling between discussions:
+- **Data coupling**: Discussions that define or depend on the same data structures
+- **Behavioral coupling**: Discussions where one's implementation requires another
+- **Conceptual coupling**: Discussions that address different facets of the same problem
+
+Group discussions into specifications where each grouping represents a **coherent feature or capability that can be independently planned and built** — with clear stages delivering incremental, testable value:
+
+- **Tightly coupled discussions belong together** — their decisions are inseparable and would produce interleaved implementation work
+- **Don't group too broadly** — if a grouping mixes unrelated concerns, the resulting specification will produce incoherent stages and tasks
+- **Don't group too narrowly** — if a grouping is too thin, it may not warrant its own specification cycle
+- **Flag cross-cutting discussions** — discussions about patterns or policies should become cross-cutting specifications rather than being grouped with feature discussions
+
+### Preserve Anchored Names
+
+**CRITICAL**: Check the `cache.anchored_names` from discovery state. These are grouping names that have existing specifications.
+
+When forming groupings:
+- If a grouping contains a majority of the same discussions as an anchored name's spec, you MUST reuse that anchored name
+- Only create new names for genuinely new groupings with no overlap
+- If an anchored spec's discussions are now scattered across multiple new groupings, note this as a **naming conflict** to present to the user
+
+→ Proceed to **C. Save to Cache**.
+
+---
+
+## C. Save to Cache
+
+Create the cache directory if needed:
+```bash
+mkdir -p docs/workflow/.cache
+```
+
+Write to `docs/workflow/.cache/discussion-consolidation-analysis.md`:
+
+```markdown
+---
+checksum: {checksum from current_state.discussions_checksum}
+generated: {ISO date}
+discussion_files:
+  - {topic1}.md
+  - {topic2}.md
+---
+
+# Discussion Consolidation Analysis
+
+## Recommended Groupings
+
+### {Suggested Specification Name}
+- **{topic-a}**: {why it belongs in this group}
+- **{topic-b}**: {why it belongs in this group}
+
+**Coupling**: {Brief explanation of what binds these together}
+
+### {Another Specification Name}
+- **{topic-d}**: {why it belongs}
+
+**Coupling**: {Brief explanation}
+
+## Independent Discussions
+- **{topic-f}**: {Why this stands alone}
+
+## Analysis Notes
+{Any additional context about the relationships discovered}
+{Note any naming conflicts with anchored specs here}
+```
+
+→ Load **[display-groupings.md](display-groupings.md)** and follow its instructions.

package/skills/start-specification/references/confirm-and-handoff.md

@@ -0,0 +1,30 @@
+# Confirm and Handoff
+
+*Reference for **[start-specification](../SKILL.md)***
+
+---
+
+## Verb Rule
+
+- No spec exists → **"Creating"**
+- Spec is `in-progress` → **"Continuing"**
+- Spec is `concluded` with pending sources → **"Continuing"**
+- Spec is `concluded` with all sources extracted → **"Refining"**
+
+## Route
+
+#### If selection is "Unify all"
+
+→ Load **[confirm-unify.md](confirm-unify.md)** and follow its instructions.
+
+#### If verb is "Creating"
+
+→ Load **[confirm-create.md](confirm-create.md)** and follow its instructions.
+
+#### If verb is "Continuing"
+
+→ Load **[confirm-continue.md](confirm-continue.md)** and follow its instructions.
+
+#### If verb is "Refining"
+
+→ Load **[confirm-refine.md](confirm-refine.md)** and follow its instructions.

package/skills/start-specification/references/confirm-continue.md

@@ -0,0 +1,90 @@
+# Confirm: Continue Specification
+
+*Reference for **[confirm-and-handoff.md](confirm-and-handoff.md)***
+
+---
+
+#### If spec is in-progress with pending sources
+
+```
+Continuing specification: {Title Case Name}
+
+Existing: docs/workflow/specification/{kebab-case-name}.md (in-progress)
+
+Sources to extract:
+  • {discussion-name} (pending)
+
+Previously extracted (for reference):
+  • {discussion-name}
+
+· · · · · · · · · · · ·
+Proceed?
+- **`y`/`yes`**
+- **`n`/`no`**
+· · · · · · · · · · · ·
+```
+
+#### If spec is in-progress with all sources extracted
+
+```
+Continuing specification: {Title Case Name}
+
+Existing: docs/workflow/specification/{kebab-case-name}.md (in-progress)
+
+All sources extracted:
+  • {discussion-name}
+  • {discussion-name}
+
+· · · · · · · · · · · ·
+Proceed?
+- **`y`/`yes`**
+- **`n`/`no`**
+· · · · · · · · · · · ·
+```
+
+#### If spec is concluded with pending sources
+
+```
+Continuing specification: {Title Case Name}
+
+Existing: docs/workflow/specification/{kebab-case-name}.md (concluded)
+
+New sources to extract:
+  • {discussion-name} (pending)
+
+Previously extracted (for reference):
+  • {discussion-name}
+
+· · · · · · · · · · · ·
+Proceed?
+- **`y`/`yes`**
+- **`n`/`no`**
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response.
+
+#### If user confirms (y)
+
+#### If spec is concluded with pending sources
+
+→ Load **[continue-concluded.md](handoffs/continue-concluded.md)** and follow its instructions.
+
+#### Otherwise
+
+→ Load **[continue.md](handoffs/continue.md)** and follow its instructions.
+
+#### If user declines (n)
+
+#### If single discussion (no menu to return to)
+
+```
+Understood. You can run /start-discussion to continue working on
+discussions, or re-run this command when ready.
+```
+
+Command ends.
+
+#### If groupings or specs menu
+
+Re-display the previous menu (the display that led to this confirmation). The user can make a different choice.

package/skills/start-specification/references/confirm-create.md

@@ -0,0 +1,73 @@
+# Confirm: Create Specification
+
+*Reference for **[confirm-and-handoff.md](confirm-and-handoff.md)***
+
+---
+
+#### If no source discussions have individual specs
+
+```
+Creating specification: {Title Case Name}
+
+Sources:
+  • {discussion-name}
+  • {discussion-name}
+
+Output: docs/workflow/specification/{kebab-case-name}.md
+
+· · · · · · · · · · · ·
+Proceed?
+- **`y`/`yes`**
+- **`n`/`no`**
+· · · · · · · · · · · ·
+```
+
+#### If any source discussion has an individual spec
+
+Note the supersession (`has_individual_spec: true`):
+
+```
+Creating specification: {Title Case Name}
+
+Sources:
+  • {discussion-name} (has individual spec — will be incorporated)
+  • {discussion-name}
+
+Output: docs/workflow/specification/{kebab-case-name}.md
+
+After completion:
+  specification/{discussion-name}.md → marked as superseded
+
+· · · · · · · · · · · ·
+Proceed?
+- **`y`/`yes`**
+- **`n`/`no`**
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response.
+
+#### If user confirms (y)
+
+#### If any source discussions have individual specs
+
+→ Load **[create-with-incorporation.md](handoffs/create-with-incorporation.md)** and follow its instructions.
+
+#### Otherwise
+
+→ Load **[create.md](handoffs/create.md)** and follow its instructions.
+
+#### If user declines (n)
+
+#### If single discussion (no menu to return to)
+
+```
+Understood. You can run /start-discussion to continue working on
+discussions, or re-run this command when ready.
+```
+
+Command ends.
+
+#### If groupings or specs menu
+
+Re-display the previous menu (the display that led to this confirmation). The user can make a different choice.

package/skills/start-specification/references/confirm-refine.md

@@ -0,0 +1,41 @@
+# Confirm: Refine Specification
+
+*Reference for **[confirm-and-handoff.md](confirm-and-handoff.md)***
+
+---
+
+```
+Refining specification: {Title Case Name}
+
+Existing: docs/workflow/specification/{kebab-case-name}.md (concluded)
+
+All sources extracted:
+  • {discussion-name}
+
+· · · · · · · · · · · ·
+Proceed?
+- **`y`/`yes`**
+- **`n`/`no`**
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response.
+
+#### If user confirms (y)
+
+→ Load **[continue.md](handoffs/continue.md)** and follow its instructions.
+
+#### If user declines (n)
+
+#### If single discussion (no menu to return to)
+
+```
+Understood. You can run /start-discussion to continue working on
+discussions, or re-run this command when ready.
+```
+
+Command ends.
+
+#### If groupings or specs menu
+
+Re-display the previous menu (the display that led to this confirmation). The user can make a different choice.

package/skills/start-specification/references/confirm-unify.md

@@ -0,0 +1,63 @@
+# Confirm: Unify All
+
+*Reference for **[confirm-and-handoff.md](confirm-and-handoff.md)***
+
+---
+
+#### If existing specifications will be superseded
+
+```
+Creating specification: Unified
+
+Sources:
+  • {discussion-name}
+  • {discussion-name}
+  ...
+
+Existing specifications to incorporate:
+  • {spec-name}.md → will be superseded
+  • {spec-name}.md → will be superseded
+
+Output: docs/workflow/specification/unified.md
+
+· · · · · · · · · · · ·
+Proceed?
+- **`y`/`yes`**
+- **`n`/`no`**
+· · · · · · · · · · · ·
+```
+
+#### If no existing specifications
+
+```
+Creating specification: Unified
+
+Sources:
+  • {discussion-name}
+  • {discussion-name}
+  ...
+
+Output: docs/workflow/specification/unified.md
+
+· · · · · · · · · · · ·
+Proceed?
+- **`y`/`yes`**
+- **`n`/`no`**
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response.
+
+#### If user confirms (y)
+
+#### If existing specifications will be superseded
+
+→ Load **[unify-with-incorporation.md](handoffs/unify-with-incorporation.md)** and follow its instructions.
+
+#### Otherwise
+
+→ Load **[unify.md](handoffs/unify.md)** and follow its instructions.
+
+#### If user declines (n)
+
+Re-display the previous menu (the display that led to this confirmation). The user can make a different choice.

package/skills/start-specification/references/display-analyze.md

@@ -0,0 +1,86 @@
+# Display: Analyze Prompt
+
+*Reference for **[start-specification](../SKILL.md)***
+
+---
+
+Prompted when multiple concluded discussions exist, no specifications exist, and cache is none or stale.
+
+## Display
+
+```
+Specification Overview
+
+{N} concluded discussions found. No specifications exist yet.
+
+Concluded discussions:
+  • {discussion-name}
+  • {discussion-name}
+  • {discussion-name}
+```
+
+List all concluded discussions from discovery output.
+
+### If in-progress discussions exist
+
+```
+---
+Discussions not ready for specification:
+These discussions are still in progress and must be concluded
+before they can be included in a specification.
+  · {discussion-name} (in-progress)
+```
+
+### Cache-Aware Message
+
+#### If cache status is "none"
+
+```
+---
+These discussions will be analyzed for natural groupings to determine
+how they should be organized into specifications. Results are cached
+and reused until discussions change.
+
+· · · · · · · · · · · ·
+Proceed with analysis?
+- **`y`/`yes`**
+- **`n`/`no`**
+· · · · · · · · · · · ·
+```
+
+#### If cache status is "stale"
+
+```
+---
+A previous grouping analysis exists but is outdated — discussions
+have changed since it was created.
+
+These discussions will be re-analyzed for natural groupings. Results
+are cached and reused until discussions change.
+
+· · · · · · · · · · · ·
+Proceed with analysis?
+- **`y`/`yes`**
+- **`n`/`no`**
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response.
+
+#### If user confirms (y)
+
+If cache is stale, delete it first:
+```bash
+rm docs/workflow/.cache/discussion-consolidation-analysis.md
+```
+
+→ Load **[analysis-flow.md](analysis-flow.md)** and follow its instructions.
+
+#### If user declines (n)
+
+```
+Understood. You can run /start-discussion to continue working on
+discussions, or re-run this command when ready.
+```
+
+**Command ends.** Control returns to the user.

package/skills/start-specification/references/display-blocks.md

@@ -0,0 +1,42 @@
+# Display: Block Scenarios
+
+*Reference for **[start-specification](../SKILL.md)***
+
+---
+
+Two terminal paths — the command stops and cannot proceed.
+
+## If no discussions exist
+
+```
+Specification Phase
+
+No discussions found.
+
+The specification phase requires concluded discussions to work from.
+Discussions capture the technical decisions, edge cases, and rationale
+that specifications are built upon.
+
+Run /start-discussion to begin documenting technical decisions.
+```
+
+**STOP.** Wait for user acknowledgment. Command ends here.
+
+## If discussions exist but none concluded
+
+```
+Specification Phase
+
+No concluded discussions found.
+
+The following discussions are still in progress:
+  · {discussion-name} (in-progress)
+  · {discussion-name} (in-progress)
+
+Specifications can only be created from concluded discussions.
+Run /start-discussion to continue working on a discussion.
+```
+
+List all in-progress discussions from discovery output.
+
+**STOP.** Wait for user acknowledgment. Command ends here.

package/skills/start-specification/references/display-groupings.md

@@ -0,0 +1,168 @@
+# Display: Groupings
+
+*Reference for **[start-specification](../SKILL.md)***
+
+---
+
+Shows when cache is valid (directly from routing) or after analysis completes. This is the most content-rich display.
+
+## A. Load Groupings
+
+Load groupings from `docs/workflow/.cache/discussion-consolidation-analysis.md`. Parse the `### {Name}` headings and their discussion lists.
+
+→ Proceed to **B. Determine Discussion Status**.
+
+---
+
+## B. Determine Discussion Status
+
+For each grouping, convert the name to kebab-case and check if a matching specification exists in the discovery `specifications` array.
+
+#### If a matching spec exists
+
+For each discussion in the grouping:
+- Look up in the spec's `sources` array (by `name` field)
+- If found → use the source's `status` (`incorporated` → `extracted`, `pending` → `pending`)
+- If NOT found → status is `pending` (new source not yet in spec)
+
+Spec status: show actual status with extraction count `({X} of {Y} sources extracted)`.
+
+**Regressed sources:** After processing the grouping's discussions, check the spec's
+`sources` array from discovery. For any source where `discussion_status` is neither
+`concluded` nor `not-found`, and the source is not already in the grouping:
+- Add it to the discussion tree with status `(extracted, reopened)`
+
+These represent sources that were incorporated but whose discussions have since
+regressed to in-progress. Sources with `discussion_status: "not-found"` (deleted
+discussions) are silently skipped — there is nothing actionable.
+
+**Extraction count:** Y = count of unique discussions in (spec sources ∪ grouping members). X = count of those with `incorporated` status in spec sources. This ensures regressed sources that dropped out of the grouping still count toward Y.
+
+#### Otherwise
+
+For each discussion: status is `ready`. Spec status: `none`.
+
+→ Proceed to **C. Display**.
+
+---
+
+## C. Display
+
+All items are first-class — every grouping (including single-discussion entries) is a numbered item.
+
+```
+Specification Overview
+
+Recommended breakdown for specifications with their source discussions.
+
+1. {Grouping Name}
+   └─ Spec: {status} {(X of Y sources extracted) if applicable}
+   └─ Discussions:
+      ├─ {discussion-name} ({status})
+      └─ {discussion-name} ({status})
+
+2. {Grouping Name}
+   └─ Spec: none
+   └─ Discussions:
+      └─ {discussion-name} (ready)
+```
+
+Use `├─` for all but the last discussion, `└─` for the last.
+
+### If in-progress discussions exist
+
+```
+---
+Discussions not ready for specification:
+These discussions are still in progress and must be concluded
+before they can be included in a specification.
+  · {discussion-name} (in-progress)
+```
+
+### Key/Legend
+
+Show only the statuses that appear in the current display.
+
+```
+---
+Key:
+
+  Discussion status:
+    extracted — content has been incorporated into the specification
+    pending   — listed as source but content not yet extracted
+    ready     — concluded and available to be specified
+    reopened  — was extracted but discussion has regressed to in-progress
+
+  Spec status:
+    none        — no specification file exists yet
+    in-progress — specification work is ongoing
+    concluded   — specification is complete
+```
+
+### Tip (show when 2+ groupings)
+
+```
+---
+Tip: To restructure groupings or pull a discussion into its own
+specification, choose "Re-analyze" and provide guidance.
+```
+
+→ Proceed to **D. Menu**.
+
+---
+
+## D. Menu
+
+Present one numbered menu entry per grouping. The verb and description depend on the grouping's spec state:
+
+- No spec exists → **Start** "{Name}" — {N} ready discussions
+- Spec is `in-progress` with pending sources → **Continue** "{Name}" — {N} source(s) pending extraction
+- Spec is `in-progress` with all extracted → **Continue** "{Name}" — all sources extracted
+- Spec is `concluded` with no pending sources → **Refine** "{Name}" — concluded spec
+- Spec is `concluded` with pending sources → **Continue** "{Name}" — {N} new source(s) to extract
+
+After all grouping entries, append meta options:
+
+- **Unify all** (only when 2+ groupings exist) — all discussions combined into one specification instead of following the recommended groupings. If specs exist, note they will be incorporated and superseded.
+- **Re-analyze groupings** (always) — current groupings are discarded and rebuilt. If specs exist, existing names are preserved. User can provide guidance in the next step.
+
+**Example assembled menu** (2 groupings, specs exist):
+
+```
+· · · · · · · · · · · ·
+1. Start "Auth Flow" — 2 ready discussions
+2. Continue "Data Model" — 1 source(s) pending extraction
+3. Unify all into single specification
+   All discussions are combined into one specification. Existing
+   specifications are incorporated and superseded.
+4. Re-analyze groupings
+   Current groupings are discarded and rebuilt. Existing
+   specification names are preserved. You can provide guidance
+   in the next step.
+
+Select an option (enter number):
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response.
+
+#### If user picks a grouping
+
+→ Load **[confirm-and-handoff.md](confirm-and-handoff.md)** and follow its instructions.
+
+#### If user picks "Unify all"
+
+Update the cache: rewrite `docs/workflow/.cache/discussion-consolidation-analysis.md` with a single "Unified" grouping containing all concluded discussions. Keep the same checksum, update the generated timestamp. Add note: `Custom groupings confirmed by user (unified).`
+
+Spec name: "Unified". Sources: all concluded discussions.
+
+→ Load **[confirm-and-handoff.md](confirm-and-handoff.md)** and follow its instructions.
+
+#### If user picks "Re-analyze"
+
+Delete the cache:
+```bash
+rm docs/workflow/.cache/discussion-consolidation-analysis.md
+```
+
+→ Load **[analysis-flow.md](analysis-flow.md)** and follow its instructions.