LCORE-1736 feature design process improvements

.claude/commands/spec-doc.md

@@ -19,3 +19,11 @@ The user may also provide a spike doc path or feature description directly.
 
 Place the spec doc at `docs/design/<feature>/<feature>.md`.  Confirm the
 feature name and path with the user.
+
+## Keep spike doc and spec doc coupled
+
+If a corresponding spike doc exists, treat the two as a coupled pair.
+Whenever you make a non-trivial update to the spec doc — a decision
+recommendation changes, an open question gets resolved, a reviewer
+comment is incorporated — **check whether the spike doc needs a
+corresponding update**. If yes, propose the update in the same turn.

.claude/commands/spike-finalize.md

@@ -0,0 +1,103 @@
+Finalize a spike after its PR has been merged: replace placeholders, verify drift, prompt about Google Docs
+
+You are finalizing a spike whose PR has been merged. The spike doc and spec
+doc now live in the repo permanently; PoC code and evidence have been
+removed. Implementation JIRAs have been filed under the parent feature
+ticket.
+
+Follow the process in `docs/contributing/howto-run-a-spike.md`, step 11
+("Finalize after merge").
+
+## Configuration
+
+Read `docs/contributing/feature-design.config` and (if present)
+`.feature-design.config.local`. Honor:
+- `auto_replace_jira_placeholders`
+- `verify_spike_spec_doc_drift`
+- `verify_no_orphan_jira_references`
+- `remind_about_google_doc_after_merge`
+- `config_announcement_at_start`
+
+Announce config files read at session start, per
+`config_announcement_at_start` (same behavior as `/spike`).
+
+## Inputs
+
+The user will identify the feature, e.g., by directory name
+(`docs/design/<feature>/`) or by spike ticket key. From this:
+- Locate the spike doc (`<feature>-spike.md`) and spec doc (`<feature>.md`).
+- Locate the parsed JIRAs directory (`docs/design/<feature>/jiras/`) if
+  it exists.
+
+## Steps
+
+### 1. Replace LCORE-???? placeholders
+
+If `auto_replace_jira_placeholders = yes`:
+
+- For each filed ticket file in `docs/design/<feature>/jiras/`, read the
+  `<!-- key: LCORE-XXXX -->` metadata.
+- Find the corresponding `LCORE-????` placeholder in the spike doc by
+  matching the ticket title (`### LCORE-???? <title>`) to the filed
+  ticket's title.
+- Replace `LCORE-????` with the real key in the spike doc.
+- Show a diff to the user before writing.
+
+If a placeholder cannot be matched to a filed ticket, list the unmatched
+items and ask the user to resolve manually.
+
+### 2. Verify spike ↔ spec doc don't drift
+
+If `verify_spike_spec_doc_drift = yes`:
+
+- Read both docs.
+- Identify decisions in the spike doc that should be reflected in the spec
+  doc (look at "Strategic decisions", "Technical decisions",
+  "Stakeholder decisions" sections).
+- Cross-check that the spec doc's Requirements / Architecture /
+  Implementation Suggestions reflect the *resolved* decisions (i.e., the
+  recommendations the reviewers accepted).
+- Report any apparent drift to the user — don't fix automatically;
+  document drift requires human judgment.
+
+### 3. Verify no orphan JIRA references
+
+If `verify_no_orphan_jira_references = yes`:
+
+- Grep for `LCORE-????` in the spike doc and the spec doc. Any remaining
+  matches are unresolved placeholders.
+- Grep for `LCORE-` references; for each found key, confirm the ticket
+  exists (via `dev-tools/fetch-jira.sh <key>` if needed). Report any that
+  return errors.
+
+### 4. PoC artifacts cleanup check
+
+Confirm `docs/design/<feature>/poc-results/` was removed before merge (per
+`remove_poc_dir_before_merge` and the howto step 10). If it still exists,
+remind the user; do not delete automatically.
+
+### 5. Google Docs reminder
+
+If `remind_about_google_doc_after_merge = yes`:
+
+Print a reminder, in this shape (adapt wording as appropriate):
+
+> Now that the spike+spec PR has merged, consider creating Google Docs
+> versions of:
+>   - the spike doc at `docs/design/<feature>/<feature>-spike.md`
+>   - the spec doc at `docs/design/<feature>/<feature>.md`
+>
+> Google Docs versions are easier for the wider team to read and comment
+> on. Markdown → Google Doc conversion: copy the rendered Markdown into
+> a new Doc, or use a converter; either way, link the resulting docs
+> back from the JIRA feature ticket so they're discoverable.
+
+Do NOT attempt to create the Google Docs yourself; this is a manual
+step the user takes.
+
+### 6. Summary
+
+Print a short end-of-session summary listing what was changed
+(placeholder replacements, files updated), what was flagged (drift,
+orphan refs, missing cleanup), and what's left for the user (Google Docs
+creation, any flagged items needing manual resolution).

.claude/commands/spike.md

@@ -5,16 +5,93 @@ You are starting a spike for a feature in the Lightspeed Core project.
 Follow the process in `docs/contributing/howto-run-a-spike.md`.  Use the
 templates it references.
 
+## Configuration
+
+Read `docs/contributing/feature-design.config` (team policy) and, if
+present, `.feature-design.config.local` at the repo root (per-developer
+overrides). The local file's settings override the team file's; keys not
+set in the local file fall through.
+
+At the start of the session, announce the configuration in the manner
+specified by `config_announcement_at_start`:
+- `silent`: no announcement.
+- `notable` (default): list which config files were read; list any
+  actively-honored non-default settings relevant to the spike workflow
+  (e.g., reviewers, default PoC ambition, decision presentation cadence);
+  list any settings changed since the last session, computed against the
+  state file at `config_state_file` (compare mtime + content hash).
+- `full`: print the resolved (team + local) config in full.
+
+After announcing, update the state file with the current mtime and hash
+of each config file.
+
+If `agent_may_suggest_config_changes_during_work` is `yes`, you may
+propose one-shot or persistent config changes mid-session when they would
+help the current work — but always ask the user before persisting.
+
+## Fetching the JIRA ticket
+
 If the user provides a JIRA ticket number (e.g., "1234" or "LCORE-1234"),
 fetch the ticket content by running `sh dev-tools/fetch-jira.sh <number>`.
 The output includes child issues — decide which linked tickets to fetch
 for additional context.
 
 Otherwise, the user will provide context about the feature directly.
 
+## Branch and working tree
+
+Before creating the spike branch:
+
+1. Confirm the proposed branch name with the user (per
+   `branch_name_pattern`).
+2. Check the working tree. If it's not clean, honor `on_dirty_working_tree`:
+   - `ask` (default): describe the situation and ask the user whether to
+     use a worktree (per `worktree_path_pattern`), move untracked files
+     aside (per `move_aside_path_pattern`), stop and let the user clean
+     up manually, or proceed anyway. Wait for an answer before acting.
+   - `worktree` / `move_aside` / `stop`: act per the policy.
+3. Create the branch off `branch_off` (default `upstream/main`) after
+   confirmation.
+
+## Drafting the spike doc
+
 When proposing JIRAs in the spike doc, specify the type for each ticket
 using `<!-- type: Task -->` or `<!-- type: Story -->` (see the JIRA ticket
-template).  Use `dev-tools/file-jiras.sh --help` for filing details.
+template).  Include the e2e kickoff Story and step-definitions counterpart
+Task as the first two proposed JIRAs by default (per
+`require_e2e_kickoff_jira` and `require_e2e_step_definitions_jira`).
+
+Use `dev-tools/file-jiras.sh --help` for filing details.
+
+## Decision presentation
+
+Honor `decision_presentation_cadence`:
+- `per_decision`: ask the user at every decision before moving on.
+- `batch`: present all decisions in one summary near the end and let the
+  user confirm/override the batch.
+- `mixed` (default): per-decision for strategic decisions; batched for
+  technical decisions.
+
+State a confidence value with each recommendation (per
+`require_confidence_per_recommendation` and `confidence_format`).
+
+## Use task tracking
+
+Use `TaskCreate` / `TaskUpdate` to track the spike phases (set up →
+research → design alternatives → PoC → spike doc → spec doc → JIRAs).
+Spikes are multi-phase; tracking improves continuity and reviewability.
+
+## Keep spike doc and spec doc coupled
+
+Treat the spike doc and the spec doc as a coupled pair. Whenever you make
+a non-trivial update to one — a decision recommendation changes, a PoC
+finding is integrated, the user overrides a default, a reviewer comment
+is incorporated — **check whether the other needs a corresponding
+update**. If yes, propose the update in the same turn.
+
+## End-of-session reminder
 
-At decision points, present what you've found and ask the user before proceeding.
-The user makes the decisions — you assist with the research and documenting.
+When the spike PR is opened (step 7 of the howto), remind the user that
+`/spike-finalize` exists and what conditions trigger it: decisions
+confirmed by reviewers, JIRAs filed via `/file-jiras`, ready to merge the
+spike PR.

.feature-design.config.local.example

@@ -0,0 +1,31 @@
+# Feature design — personal overrides (example)
+# =============================================================================
+#
+# Copy this file to `.feature-design.config.local` (gitignored) and override
+# any setting from `docs/contributing/feature-design.config`. Keys you don't
+# set fall through to the team policy.
+#
+# Suitable per-dev overrides include:
+#   - pr_template_output_path  (where you keep PR-body drafts)
+#   - default_poc_ambition     (some prefer minimal, some ambitious)
+#   - decision_presentation_cadence  (some prefer everything per_decision)
+#   - confidence_format        (numeric vs qualitative preference)
+#
+# Settings you should NOT override here (they're conventions, not preferences):
+#   - feature_dir, *_filename, jira_dir_path, ticket_placeholder_format
+#   - require_e2e_kickoff_jira, require_e2e_step_definitions_jira
+#   - default_strategic_reviewer, default_technical_reviewer
+#   - any include_*_section setting that's part of the team's doc shape
+
+# Example: keep PR-body drafts in your home dir instead of /tmp.
+# pr_template_output_path = ~/work/pr-drafts/{prefix}-{ticket}-pr.txt
+
+# Example: prefer to be asked at every decision (strategic + technical)
+# rather than batching technical decisions.
+# decision_presentation_cadence = per_decision
+
+# Example: use qualitative confidence labels instead of percentages.
+# confidence_format = qualitative
+
+# Example: less ambitious PoCs by default.
+# default_poc_ambition = moderate

.gitignore

@@ -196,4 +196,6 @@ requirements.*.backup
 local-run.yaml
 
 # Sisyphus planning files
-.sisyphus/
+.sisyphus/
+# Per-developer feature design overrides (see docs/contributing/feature-design.config)
+.feature-design.config.local