@leeovery/claude-technical-workflows 2.1.19 → 2.1.21

package/skills/start-discussion/references/handle-selection.md

@@ -0,0 +1,54 @@
+# Handle Selection
+
+*Reference for **[start-discussion](../SKILL.md)***
+
+---
+
+Route based on the user's choice from the options display.
+
+#### If user chose "From research"
+
+User chose to start from research (e.g., "research 1", "1", "from research", or a topic name).
+
+**If user specified a topic inline** (e.g., "research 2", "2", or topic name):
+- Identify the selected topic from the numbered list
+- Control returns to the backbone
+
+**If user just said "from research" without specifying:**
+```
+Which research topic would you like to discuss? (Enter a number or topic name)
+```
+
+**STOP.** Wait for response.
+
+#### If user chose "Continue discussion"
+
+User chose to continue a discussion (e.g., "continue auth-flow" or "continue discussion").
+
+**If user specified a discussion inline** (e.g., "continue auth-flow"):
+- Identify the selected discussion from the list
+- Control returns to the backbone
+
+**If user just said "continue discussion" without specifying:**
+```
+Which discussion would you like to continue?
+```
+
+**STOP.** Wait for response.
+
+#### If user chose "Fresh topic"
+
+User wants to start a fresh discussion. Control returns to the backbone.
+
+#### If user chose "refresh"
+
+```
+Refreshing analysis...
+```
+
+Delete the cache file:
+```bash
+rm docs/workflow/.cache/research-analysis.md
+```
+
+→ Return to **Step 3** to re-analyze.

package/skills/start-discussion/references/invoke-skill.md

@@ -0,0 +1,30 @@
+# Invoke the Skill
+
+*Reference for **[start-discussion](../SKILL.md)***
+
+---
+
+This skill's purpose is now fulfilled.
+
+Invoke the [technical-discussion](../../technical-discussion/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
+
+**Example handoff (from research):**
+```
+Discussion session for: {topic}
+Output: docs/workflow/discussion/{topic}.md
+
+Research reference:
+Source: docs/workflow/research/{filename}.md (lines {start}-{end})
+Summary: {the 1-2 sentence summary from the research analysis}
+
+Invoke the technical-discussion skill.
+```
+
+**Example handoff (continuing or fresh):**
+```
+Discussion session for: {topic}
+Source: {existing discussion | fresh}
+Output: docs/workflow/discussion/{topic}.md
+
+Invoke the technical-discussion skill.
+```

package/skills/start-discussion/references/research-analysis.md

@@ -0,0 +1,72 @@
+# Research Analysis
+
+*Reference for **[start-discussion](../SKILL.md)***
+
+---
+
+This step only runs when research files exist.
+
+Use `cache.status` from discovery to determine the approach:
+
+#### If cache.status is "valid"
+
+```
+Using cached research analysis (unchanged since {cache.generated})
+```
+
+Load the topics from `docs/workflow/.cache/research-analysis.md` and proceed.
+
+#### If cache.status is "stale" or "none"
+
+```
+Analyzing research documents...
+```
+
+Read each research file and extract key themes and potential discussion topics. For each theme:
+- Note the source file and relevant line numbers
+- Summarize what the theme is about in 1-2 sentences
+- Identify key questions or decisions that need discussion
+
+**Be thorough**: This analysis will be cached, so identify ALL potential topics:
+- Major architectural decisions
+- Technical trade-offs mentioned
+- Open questions or concerns raised
+- Implementation approaches discussed
+- Integration points with external systems
+- Security or performance considerations
+- Edge cases or error handling mentioned
+
+**Save to cache:**
+
+Ensure the cache directory exists:
+```bash
+mkdir -p docs/workflow/.cache
+```
+
+Create/update `docs/workflow/.cache/research-analysis.md`:
+
+```markdown
+---
+checksum: {research.checksum from discovery}
+generated: YYYY-MM-DDTHH:MM:SS  # Use current ISO timestamp
+research_files:
+  - {filename1}.md
+  - {filename2}.md
+---
+
+# Research Analysis Cache
+
+## Topics
+
+### {Theme name}
+- **Source**: {filename}.md (lines {start}-{end})
+- **Summary**: {1-2 sentence summary}
+- **Key questions**: {what needs deciding}
+
+### {Another theme}
+- **Source**: {filename}.md (lines {start}-{end})
+- **Summary**: {1-2 sentence summary}
+- **Key questions**: {what needs deciding}
+```
+
+**Cross-reference**: For each topic, note if a discussion already exists (from `discussions.files` in discovery).

package/skills/start-implementation/SKILL.md

@@ -30,6 +30,7 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. Presen
 
 **CRITICAL**: This guidance is mandatory.
 
+- **Silent processing**: Do NOT narrate your internal reasoning. Never output discovery field values, routing decisions, cache status, or prerequisite checks. The first user-visible output must be the display content itself.
 - After each user interaction, STOP and wait for their response before proceeding
 - Never assume or anticipate user choices
 - Even if the user's initial prompt seems to answer a question, still confirm with them at the appropriate step

package/skills/start-planning/SKILL.md

@@ -30,6 +30,7 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. Presen
 
 **CRITICAL**: This guidance is mandatory.
 
+- **Silent processing**: Do NOT narrate your internal reasoning. Never output discovery field values, routing decisions, cache status, or prerequisite checks. The first user-visible output must be the display content itself.
 - After each user interaction, STOP and wait for their response before proceeding
 - Never assume or anticipate user choices
 - Even if the user's initial prompt seems to answer a question, still confirm with them at the appropriate step

package/skills/start-review/SKILL.md

@@ -30,6 +30,7 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. Presen
 
 **CRITICAL**: This guidance is mandatory.
 
+- **Silent processing**: Do NOT narrate your internal reasoning. Never output discovery field values, routing decisions, cache status, or prerequisite checks. The first user-visible output must be the display content itself.
 - After each user interaction, STOP and wait for their response before proceeding
 - Never assume or anticipate user choices
 - Even if the user's initial prompt seems to answer a question, still confirm with them at the appropriate step
@@ -71,6 +72,8 @@ Parse the discovery output to understand:
 
 **From `state` section:**
 - `scenario` - one of: `"no_plans"`, `"single_plan"`, `"multiple_plans"`
+- `implemented_count` - plans with implementation_status != "none"
+- `completed_count` - plans with implementation_status == "completed"
 
 **IMPORTANT**: Use ONLY this script for discovery. Do NOT run additional bash commands (ls, head, cat, etc.) to gather state - the script provides everything needed.
 
@@ -102,29 +105,67 @@ Plans exist.
 
 ---
 
-## Step 3: Present Plans and Select
+## Step 3: Present Plans and Select Scope
 
-Present all discovered plans to help the user make an informed choice.
+Present all discovered plans with implementation status to help the user understand what's reviewable.
 
 **Present the full state:**
 
 ```
-Available Plans:
+Review Phase
 
-  1. {topic-1} ({status}) - format: {format}, spec: {exists|missing}
-  2. {topic-2} ({status}) - format: {format}, spec: {exists|missing}
+Reviewable:
+  1. ✓ {topic-1} (completed) - format: {format}, spec: {exists|missing}
+  2. ▶ {topic-2} (in-progress) - format: {format}, spec: {exists|missing}
 
-· · · · · · · · · · · ·
-Which plan would you like to review the implementation for? (Enter a number or name)
+Not reviewable:
+  · {topic-3} [no implementation]
+```
+
+**Formatting rules:**
+
+Reviewable (numbered, selectable):
+- **`✓`** — implementation_status: completed
+- **`▶`** — implementation_status: in-progress
+
+Not reviewable (not numbered, not selectable):
+- **`·`** — implementation_status: none
+
+Omit either section entirely if it has no entries.
+
+**Then route based on what's reviewable:**
+
+#### If no reviewable plans
+
+```
+No implemented plans found.
+
+The review phase requires at least one plan with an implementation.
+Please run /start-implementation first.
 ```
 
-**If single plan exists (auto-select):**
+**STOP.** Wait for user to acknowledge before ending.
+
+#### If single reviewable plan
+
+```
+Auto-selecting: {topic} (only reviewable plan)
+Scope: single
 ```
-Auto-selecting: {topic} (only available plan)
+
+→ Proceed directly to **Step 5**.
+
+#### If multiple reviewable plans
+
 ```
-→ Proceed directly to **Step 4**.
+· · · · · · · · · · · ·
+What scope would you like to review?
 
-**If multiple plans exist:**
+- **`s`/`single`** — Review one plan's implementation
+- **`m`/`multi`** — Review selected plans together (cross-cutting)
+- **`a`/`all`** — Review all implemented plans (full product)
+· · · · · · · · · · · ·
+```
 
 **STOP.** Wait for user response.
 
@@ -132,23 +173,37 @@ Auto-selecting: {topic} (only available plan)
 
 ---
 
-## Step 4: Identify Implementation Scope
+## Step 4: Plan Selection
+
+This step only applies for `single` or `multi` scope chosen in Step 3.
+
+#### If scope is "all"
+
+All reviewable plans are included. No selection needed.
+
+→ Proceed directly to **Step 5**.
 
-Ask the user what code to review:
+#### If scope is "single"
 
 ```
 · · · · · · · · · · · ·
-What code should I review?
-
-- **`a`/`all`** — All changes since the plan was created
-- **`g`/`git`** — Identify from git status
-- Specific directories or files — tell me which
+Which plan would you like to review? (Enter a number from Step 3)
 · · · · · · · · · · · ·
 ```
 
 **STOP.** Wait for user response.
 
-If they choose specific directories/files, ask them to specify.
+→ Proceed to **Step 5**.
+
+#### If scope is "multi"
+
+```
+· · · · · · · · · · · ·
+Which plans to include? (Enter numbers separated by commas, e.g. 1,3)
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response.
 
 → Proceed to **Step 5**.
 
@@ -160,14 +215,25 @@ After completing the steps above, this skill's purpose is fulfilled.
 
 Invoke the [technical-review](../technical-review/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
 
-**Example handoff:**
+**Example handoff (single):**
 ```
 Review session for: {topic}
+Review scope: single
 Plan: docs/workflow/planning/{topic}.md
 Format: {format}
 Plan ID: {plan_id} (if applicable)
 Specification: {specification} (exists: {true|false})
-Scope: {all changes | specific paths | from git status}
+
+Invoke the technical-review skill.
+```
+
+**Example handoff (multi/all):**
+```
+Review session for: {scope description}
+Review scope: {multi | all}
+Plans:
+  - docs/workflow/planning/{topic-1}.md (format: {format}, spec: {spec})
+  - docs/workflow/planning/{topic-2}.md (format: {format}, spec: {spec})
 
 Invoke the technical-review skill.
 ```

package/skills/start-review/scripts/discovery.sh

@@ -45,6 +45,8 @@ echo ""
 echo "plans:"
 
 plan_count=0
+implemented_count=0
+completed_count=0
 
 if [ -d "$PLAN_DIR" ] && [ -n "$(ls -A "$PLAN_DIR" 2>/dev/null)" ]; then
     echo "  exists: true"
@@ -73,6 +75,14 @@ if [ -d "$PLAN_DIR" ] && [ -n "$(ls -A "$PLAN_DIR" 2>/dev/null)" ]; then
             spec_exists="true"
         fi
 
+        # Check implementation status
+        impl_tracking="docs/workflow/implementation/${name}/tracking.md"
+        impl_status="none"
+        if [ -f "$impl_tracking" ]; then
+            impl_status_val=$(extract_field "$impl_tracking" "status")
+            impl_status=${impl_status_val:-"in-progress"}
+        fi
+
         echo "    - name: \"$name\""
         echo "      topic: \"$topic\""
         echo "      status: \"$status\""
@@ -83,8 +93,15 @@ if [ -d "$PLAN_DIR" ] && [ -n "$(ls -A "$PLAN_DIR" 2>/dev/null)" ]; then
         if [ -n "$plan_id" ]; then
             echo "      plan_id: \"$plan_id\""
         fi
+        echo "      implementation_status: \"$impl_status\""
 
         plan_count=$((plan_count + 1))
+        if [ "$impl_status" != "none" ]; then
+            implemented_count=$((implemented_count + 1))
+        fi
+        if [ "$impl_status" = "completed" ]; then
+            completed_count=$((completed_count + 1))
+        fi
     done
 
     echo "  count: $plan_count"
@@ -103,6 +120,8 @@ echo "state:"
 
 echo "  has_plans: $([ "$plan_count" -gt 0 ] && echo "true" || echo "false")"
 echo "  plan_count: $plan_count"
+echo "  implemented_count: $implemented_count"
+echo "  completed_count: $completed_count"
 
 # Determine workflow state for routing
 if [ "$plan_count" -eq 0 ]; then

package/skills/start-specification/SKILL.md

@@ -30,6 +30,7 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. Presen
 
 **CRITICAL**: This guidance is mandatory.
 
+- **Silent processing**: Do NOT narrate your internal reasoning. Never output discovery field values, routing decisions, cache status, or prerequisite checks. The first user-visible output must be the display content itself.
 - After each user interaction, STOP and wait for their response before proceeding
 - Never assume or anticipate user choices
 - Even if the user's initial prompt seems to answer a question, still confirm with them at the appropriate step

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

@@ -24,7 +24,6 @@ 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.
@@ -33,10 +32,11 @@ before they can be included in a specification.
 
 ### Cache-Aware Message
 
+No `---` separator before these messages.
+
 #### 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.
@@ -51,7 +51,6 @@ Proceed with analysis?
 #### If cache status is "stale"
 
 ```
----
 A previous grouping analysis exists but is outdated — discussions
 have changed since it was created.
 

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

@@ -67,12 +67,11 @@ Recommended breakdown for specifications with their source discussions.
       └─ {discussion-name} (ready)
 ```
 
-Use `├─` for all but the last discussion, `└─` for the last.
+**Formatting is exact**: Output the tree structure exactly as shown above — preserve all indentation spaces, blank lines between groupings, and `├─`/`└─` characters. Do not flatten or compress the spacing.
 
 ### 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.
@@ -81,10 +80,9 @@ before they can be included in a specification.
 
 ### Key/Legend
 
-Show only the statuses that appear in the current display.
+Show only the statuses that appear in the current display. No `---` separator before this section.
 
 ```
----
 Key:
 
   Discussion status:
@@ -101,8 +99,9 @@ Key:
 
 ### Tip (show when 2+ groupings)
 
+No `---` separator before this section.
+
 ```
----
 Tip: To restructure groupings or pull a discussion into its own
 specification, choose "Re-analyze" and provide guidance.
 ```
@@ -133,17 +132,19 @@ After all grouping entries, append meta options:
 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.
+   `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.
+   `Current groupings are discarded and rebuilt. Existing`
+   `specification names are preserved. You can provide guidance`
+   `in the next step.`
 
 Select an option (enter number):
 · · · · · · · · · · · ·
 ```
 
+**Formatting is exact**: Reproduce the menu exactly as shown above — descriptions are indented 3 spaces and wrapped in backticks.
+
 **STOP.** Wait for user response.
 
 #### If user picks a grouping

package/skills/start-specification/references/display-single-grouped.md

@@ -27,10 +27,11 @@ Single concluded discussion found with existing multi-source specification.
       └─ {source-name} (extracted, reopened)
 ```
 
+**Formatting is exact**: Output the tree structure exactly as shown above — preserve all indentation spaces and `├─`/`└─` characters. Do not flatten or compress the spacing.
+
 ### 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.
@@ -39,10 +40,9 @@ before they can be included in a specification.
 
 ### Key/Legend
 
-Show only the statuses that appear in the current display.
+Show only the statuses that appear in the current display. No `---` separator before this section.
 
 ```
----
 Key:
 
   Discussion status:
@@ -58,7 +58,6 @@ Key:
 ## After Display
 
 ```
----
 Automatically proceeding with "{Spec Title Case Name}".
 ```
 

package/skills/start-specification/references/display-single-has-spec.md

@@ -21,10 +21,11 @@ Single concluded discussion found with existing specification.
       └─ {discussion-name} (extracted)
 ```
 
+**Formatting is exact**: Output the tree structure exactly as shown above — preserve all indentation spaces and `├─`/`└─` characters. Do not flatten or compress the spacing.
+
 ### 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.
@@ -33,8 +34,9 @@ before they can be included in a specification.
 
 ### Key/Legend
 
+No `---` separator before this section.
+
 ```
----
 Key:
 
   Discussion status:
@@ -47,7 +49,6 @@ Key:
 ## After Display
 
 ```
----
 Automatically proceeding with "{Title Case Name}".
 ```
 

package/skills/start-specification/references/display-single-no-spec.md

@@ -19,10 +19,11 @@ Single concluded discussion found.
       └─ {discussion-name} (ready)
 ```
 
+**Formatting is exact**: Output the tree structure exactly as shown above — preserve all indentation spaces and `├─`/`└─` characters. Do not flatten or compress the spacing.
+
 ### 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.
@@ -31,8 +32,9 @@ before they can be included in a specification.
 
 ### Key/Legend
 
+No `---` separator before this section.
+
 ```
----
 Key:
 
   Discussion status:
@@ -45,7 +47,6 @@ Key:
 ## After Display
 
 ```
----
 Automatically proceeding with "{Title Case Name}".
 ```
 

package/skills/start-specification/references/display-specs-menu.md

@@ -26,6 +26,8 @@ For each non-superseded specification from discovery output, display as nested t
       └─ {source-name} (extracted)
 ```
 
+**Formatting is exact**: Output the tree structure exactly as shown above — preserve all indentation spaces and `├─`/`└─` characters. Do not flatten or compress the spacing.
+
 Determine discussion status from the spec's `sources` array:
 - `incorporated` + `discussion_status: concluded` or `not-found` → `extracted`
 - `incorporated` + `discussion_status: other` (e.g. `in-progress`) → `extracted, reopened`
@@ -46,7 +48,6 @@ Concluded discussions not in a specification:
 ### 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.
@@ -55,10 +56,9 @@ before they can be included in a specification.
 
 ### Key/Legend
 
-Show only the statuses that appear in the current display.
+Show only the statuses that appear in the current display. No `---` separator before this section.
 
 ```
----
 Key:
 
   Discussion status:
@@ -72,17 +72,17 @@ Key:
 
 ### Cache-Aware Message
 
+No `---` separator before these messages.
+
 #### If cache status is "none"
 
 ```
----
 No grouping analysis exists.
 ```
 
 #### If cache status is "stale"
 
 ```
----
 A previous grouping analysis exists but is outdated — discussions
 have changed since it was created. Re-analysis is required.
 ```
@@ -104,9 +104,9 @@ List "Analyze for groupings (recommended)" first, then one entry per existing no
 ```
 · · · · · · · · · · · ·
 1. Analyze for groupings (recommended)
-   All discussions are analyzed for natural groupings. Existing
-   specification names are preserved. You can provide guidance
-   in the next step.
+   `All discussions are analyzed for natural groupings. Existing`
+   `specification names are preserved. You can provide guidance`
+   `in the next step.`
 2. Continue "Auth Flow" — in-progress
 3. Refine "Data Model" — concluded
 
@@ -114,6 +114,8 @@ Select an option (enter number):
 · · · · · · · · · · · ·
 ```
 
+Menu descriptions are wrapped in backticks to visually distinguish them from the choice labels.
+
 **STOP.** Wait for user response.
 
 #### If user picks "Analyze for groupings"