LCORE-1736 feature design process improvements#1695
Merged
tisnik merged 7 commits intoMay 12, 2026
Merged
Conversation
Introduce a two-tier configuration for the feature design process: - docs/contributing/feature-design.config — team-policy conventions (mostly read-only for individual contributors). Defines section inclusion (yes / no / if_applicable), naming patterns, branching policy, decision-presentation cadence, PoC behavior, JIRA conventions including the e2e-kickoff + step-definitions defaults, reviewer defaults (@sbunciak strategic, @tisnik technical), config-application UX, and the new remind_about_google_doc_after_merge setting. - .feature-design.config.local.example — template for per-developer overrides. The actual .feature-design.config.local at the repo root is gitignored. Settings unset locally fall through to the team file. The third value `if_applicable` joins `yes`/`no` for include flags. It signals "the agent decides based on whether the feature actually has this concern" — useful for sections like security, observability, capacity planning, latency/cost, etc.
Apply the conventions from docs/contributing/feature-design.config to
the templates, howtos, and the top-level contributing guide.
Spike template (templates/spike-template.md):
- Three audience sections (Strategic / Technical / Stakeholder); the
Stakeholder section is `if_applicable` and removed when the feature
did not originate from a named team.
- Confidence required per recommendation (numeric or qualitative per
config).
- Out-of-scope section is required.
- E2E kickoff Story (write feature files, no implementation) and
step-definitions Task counterpart are pre-filled stubs as the first
two proposed JIRAs (per `require_e2e_kickoff_jira` and
`require_e2e_step_definitions_jira`).
- New sections (`if_applicable`): PoC findings, incidental findings,
proposed incidental JIRAs, external-input-needed, glossary.
Spec doc template (templates/spec-doc-template.md):
- Acceptance test surface section (always present) — feeds the e2e
kickoff JIRA's feature-file authoring.
- Aspect-specific concerns regrouped: Latency/Cost, Observability,
Capacity planning, Failure modes, Security, Migration/backcompat,
Telemetry/data privacy, Feature flags/rollout, Runbook/oncall,
Internationalization, API versioning, Rate limiting/quotas — all
`if_applicable`.
- Architecture sub-sections (Trigger mechanism, Storage, Configuration,
API changes, Error handling, Security, Migration) marked
`if_applicable` rather than always-present.
- Open Questions traceability requirement: each item must trace back
to its origin (spike decision, PoC finding, or reviewer comment).
Howtos:
- howto-run-a-spike.md gains a Configuration paragraph, three-audience
guidance, confidence and out-of-scope requirements, the e2e-kickoff
convention, a new step 11 ("Finalize after merge") pointing at
/spike-finalize, and an updated checklist.
- howto-write-a-spec-doc.md gains a Configuration paragraph and
describes the new Acceptance test surface and aspect-specific
concerns sections; Open Questions traceability is documented.
- howto-organize-poc-output.md is rewritten from a rigid numbered-file
scheme to principles. Covers two common PoC shapes (code PoC vs
data/experimental) without prescribing filenames.
Top-level guide (docs/contributing_guide.md):
- Adds step 6 (`/spike-finalize`) to the Feature design process flow.
- Points readers at the new feature-design.config and
.feature-design.config.local files.
/spike (.claude/commands/spike.md): - Reads docs/contributing/feature-design.config and (if present) .feature-design.config.local at session start. - Announces config files loaded, plus actively-honored non-default settings and items changed since last session, per `config_announcement_at_start` (default `notable`). - Maintains a state file at `config_state_file` (default `.claude/feature-design.last-seen`) for change detection. - May propose one-shot or persistent config changes mid-session if `agent_may_suggest_config_changes_during_work = yes` (default). - Honors `on_dirty_working_tree` (default `ask`): describes the situation and asks whether to use a worktree, move untracked files aside, stop, or proceed. Confirms branch name before creating. - Honors `decision_presentation_cadence` (default `mixed`): per-decision for strategic, batched for technical. - Includes the e2e kickoff Story and step-definitions Task as the first two proposed JIRAs by default. - Uses TaskCreate/TaskUpdate to track spike phases. - Reminds the user about /spike-finalize at PR-open time. /spike-finalize (.claude/commands/spike-finalize.md, new): - Replaces LCORE-???? placeholders in the spike doc with real keys read from the filed-tickets metadata under jiras/. - Verifies the spike doc and spec doc don't drift on the resolved decisions. - Greps for orphan LCORE-???? references across both docs. - Reminds about removing poc-results/ if it wasn't already cleaned up. - Reminds the user to create Google Docs versions of the spike and spec docs (per `remind_about_google_doc_after_merge = yes`).
Six small refinements to the feature design process, applied before
opening the LCORE-1736 PR. Each is small; together they cover the
follow-up feedback from the review of the original LCORE-1736 changeset.
1. Trim ### Test patterns subsection in spec-doc-template
The 5-bullet generic list (pytest framework, AsyncMock pattern, etc.)
duplicated the project-wide testing conventions in CLAUDE.md.
Replaced with a one-line pointer to CLAUDE.md and a TODO for
feature-specific test considerations only.
2. Trim ### Config pattern subsection in spec-doc-template
Same shape of duplication: the ConfigurationBase / extra="forbid" /
Field()/@model_validator note is in CLAUDE.md's Configuration
section. Replaced with a pointer plus a TODO for feature-specific
config schemas.
3. Add "Tools used to create PR" section to spike-pr-template
Spike PRs are typically heavy on AI assistance; transparency
warrants the same Assisted-by/Generated-by note that the project's
default PR template carries. Adopted just this section from the
project default; deliberately did NOT pull in the broader project
PR template's Type-of-change/Checklist/Testing sections (those
don't fit the spike PR shape, and the spike-pr template already
carries its own structured asks).
4. Two new aspect sections in spec-doc-template (per A5 defaults)
- "Migration tool patterns": invocation/semantics of any user-facing
migration tool that ships with the feature
- "Rollout / deployment plan": rollout sequence (distinct from the
existing "Feature flags / rollout" which is the flag mechanism)
Both registered as `if_applicable` in feature-design.config.
5. Spike-type-specific PoC notes (per A5 defaults)
Added two short subsections to howto-organize-poc-output.md:
- "Performance-focused spikes": include benchmark methodology, raw
measurements, baseline comparison
- "Security-focused spikes": include threat model, attack scenarios,
coordinate with security reviewer on what's public vs restricted
6. Branch-naming consolidation
feature-design.config is now the canonical source for the
spike-specific branch name pattern. Renamed the placeholder from
`{slug}` to `{short-description}` for clarity. Updated
howto-run-a-spike.md step 1 to point at the config rather than
restate the convention. Project CLAUDE.md retains the broader
non-spike branch convention (`lcore-XXXX-short-description`); the
spike pattern is now its extension.
7. Spike↔spec doc coupling exhortation
Added to /spike and /spec-doc skills: whenever a non-trivial update
is made to either doc (decision change, PoC finding integrated,
reviewer override, open question resolved), the agent must check
whether the other doc needs a corresponding update and propose it
in the same turn. Drift is the most common process failure that
/spike-finalize has to fix retroactively; cheaper to prevent.
…nt conventions Retroactive update of the reference spike doc (docs/design/conversation-compaction/conversation-compaction-spike.md) so that it teaches the conventions documented in docs/contributing/feature-design.config and docs/contributing/templates/spike-template.md. Changes that were safe to apply: 1. Audience-section header rename - "Decisions for @ptisnovs and @sbunciak" → "Strategic decisions — for @ptisnovs and @sbunciak" - "Technical decisions for @ptisnovs" → "Technical decisions — for @ptisnovs" 2. Confidence value added for Decision 2 The conversation transcript explicitly states: "Confidence: 85% that additive-first is better for production". Added as a quoted provenance line under the Decision 2 recommendation. Confidence values for other decisions could not be reliably recovered from the transcript and are left absent rather than fabricated. 3. JIRA placeholders → real ticket keys (LCORE-1569..LCORE-1575) The original 7 proposed JIRAs were filed as LCORE-1569..LCORE-1575 but the spike doc retained the LCORE-???? placeholders. Replaced each placeholder with the filed key. Noted the title rename for LCORE-1574 (filed as "Integration tests" rather than the original "Verify test coverage"). 4. E2E kickoff Story + step-definitions Task stubs added at the top of Proposed JIRAs Reflect the post-spike convention. Stubs include a reconciliation note pointing at the existing LCORE-1673 ("E2E tests for conversation compaction") which holds e2e work as a single ticket; reconciliation between LCORE-1673 and these stubs is pending coordination (left to the user / @ptisnovs). 5. Header note in the Overview section explaining the retroactive update. Changes deliberately not applied (per honest assessment): - Out-of-scope section: the spike conversation transcript did not contain explicit defer/scope statements that could be reliably attributed to the spike author. Adding speculative content would risk misrepresenting the original spike. - Confidence values for Decisions other than Decision 2: not recoverable from the transcript without intensive search; better absent than fabricated. - Heading-level demotion (H1→H2 throughout): purely structural; the doc as it stands is readable and aligned in spirit with the new template even if the literal heading levels differ. The spike doc remains the deliverable for LCORE-1314; this update adjusts how it presents itself, not what it decided.
Contributor
|
Warning Rate limit exceeded
You’ve run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (1)
WalkthroughThis PR establishes a comprehensive feature-design workflow system, introducing configuration files, process documentation, practical how-to guides, and document templates to standardize spike and spec-doc development practices. It applies the new workflow to an existing spike document as a concrete example. ChangesFeature-Design Workflow System
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
✨ Simplify code
Tip 💬 Introducing Slack Agent: The best way for teams to turn conversations into code.Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.
Built for teams:
One agent for your entire SDLC. Right inside Slack. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
…on kickoff + step-defs The two kickoff/step-defs JIRAs added during the reference-spike backport have now been filed under LCORE-1631: - LCORE-1673 — restructured from "E2E tests for conversation compaction" to "E2E feature files for conversation compaction (no step implementation)" via PUT (description + title rewritten to match the LCORE-836-approved kickoff Story shape). - LCORE-2230 — newly created "Implement behave step definitions for conversation compaction feature files" Task; blocked by LCORE-1673 and the implementation tickets (LCORE-1569..LCORE-1573). Resolves all remaining `LCORE-????` placeholders in the spike doc: - Section heading (kickoff Story): LCORE-1673 - Section heading (step-defs Task): LCORE-2230 - `<!-- key: -->` metadata comments for both - Inline references within bodies: "sibling ticket (LCORE-...)", "step definitions land in LCORE-...", "**Blocks**:", "authored in LCORE-...", "back to LCORE-... kickoff", "**Blocked by**: LCORE-..." Filed via `dev-tools/file-jiras.sh` against `docs/design/conversation-compaction/jiras/00-lcore-1673-amend.md` (PUT, key in metadata) and `01-step-defs.md` (POST; key written back into the file).
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/design/conversation-compaction/conversation-compaction-spike.md (1)
175-181:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winFix heading level jump under “Proposed JIRAs”.
Line 181 starts at
###directly under a#heading, which triggersMD001. Increment by one level (use##for ticket headings in this section).🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/design/conversation-compaction/conversation-compaction-spike.md` around lines 175 - 181, The "Proposed JIRAs" section currently uses a top-level H1 ("# Proposed JIRAs") followed immediately by ticket headings written as "### LCORE-1673", causing an MD001 heading-level jump; update the ticket heading lines (e.g., the "### LCORE-1673: E2E feature files for conversation compaction (no step implementation)" line) to use one level higher ("##") so they sit directly under the "Proposed JIRAs" header and remove the level jump.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/contributing/howto-organize-poc-output.md`:
- Around line 94-99: The markdown fenced code block showing the directory tree
in the docs/contributing/howto-organize-poc-output.md file is missing a language
identifier (MD040); update the fenced block that contains the poc-results/ tree
to use ```text as the opening fence so the snippet is explicitly marked as plain
text and markdownlint passes.
In `@docs/contributing/templates/spec-doc-template.md`:
- Around line 146-149: Update the header and any occurrences of the term to use
the hyphenated form "on-call" for consistency: change the header "### Runbook /
oncall implications" to "### Runbook / on-call implications" and replace the
inline phrase "What oncall needs to know; new alerts, new failure modes,
recovery procedures." with "What on-call needs to know; new alerts, new failure
modes, recovery procedures." (search for "oncall" in this section to ensure all
instances are updated).
In `@docs/design/conversation-compaction/conversation-compaction-spike.md`:
- Around line 230-244: Several fenced code blocks in the markdown (notably the
"Agentic tool instruction" fenced examples and the other examples containing
"Read the \"Architecture\" section..." and the short `text` blocks) lack
surrounding blank lines and/or explicit language tags, which triggers
markdownlint MD031/MD040; fix by adding a blank line before and after each
fenced block and ensure each fence begins with a language tag (e.g., ```text) so
all fenced blocks are separated from surrounding text and explicitly labeled;
apply the same normalization to the other similar fenced blocks in the document.
---
Outside diff comments:
In `@docs/design/conversation-compaction/conversation-compaction-spike.md`:
- Around line 175-181: The "Proposed JIRAs" section currently uses a top-level
H1 ("# Proposed JIRAs") followed immediately by ticket headings written as "###
LCORE-1673", causing an MD001 heading-level jump; update the ticket heading
lines (e.g., the "### LCORE-1673: E2E feature files for conversation compaction
(no step implementation)" line) to use one level higher ("##") so they sit
directly under the "Proposed JIRAs" header and remove the level jump.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: fde10819-985f-4d08-954d-5a998ff541a8
📒 Files selected for processing (14)
.claude/commands/spec-doc.md.claude/commands/spike-finalize.md.claude/commands/spike.md.feature-design.config.local.example.gitignoredocs/contributing/feature-design.configdocs/contributing/howto-organize-poc-output.mddocs/contributing/howto-run-a-spike.mddocs/contributing/howto-write-a-spec-doc.mddocs/contributing/templates/spec-doc-template.mddocs/contributing/templates/spike-pr-template.mddocs/contributing/templates/spike-template.mddocs/contributing_guide.mddocs/design/conversation-compaction/conversation-compaction-spike.md
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (9)
- GitHub Check: build-pr
- GitHub Check: E2E: server mode / ci / group 1
- GitHub Check: E2E: server mode / ci / group 2
- GitHub Check: E2E: server mode / ci / group 3
- GitHub Check: E2E: library mode / ci / group 1
- GitHub Check: E2E: library mode / ci / group 2
- GitHub Check: E2E: library mode / ci / group 3
- GitHub Check: E2E Tests for Lightspeed Evaluation job
- GitHub Check: Konflux kflux-prd-rh02 / lightspeed-stack-on-pull-request
🧰 Additional context used
🧠 Learnings (2)
📚 Learning: 2026-04-15T18:53:54.785Z
Learnt from: Lifto
Repo: lightspeed-core/lightspeed-stack PR: 1510
File: src/models/requests.py:742-769
Timestamp: 2026-04-15T18:53:54.785Z
Learning: In `src/models/requests.py`, keep `ResponsesRequest.validate_body_size` using `json.dumps(values)` with Python defaults (including ASCII escaping and the default separators). This default formatting is intentional to make the 65,536-character limit conservatively strict (accounting for small encoding/format overhead). Do not recommend changing it to `ensure_ascii=False` or using compact separators for this validator, since an exact wire-format byte match with the client payload is not achievable via `json.dumps` anyway.
Applied to files:
.feature-design.config.local.example.gitignore
📚 Learning: 2026-04-20T15:09:45.119Z
Learnt from: major
Repo: lightspeed-core/lightspeed-stack PR: 1548
File: src/app/endpoints/rlsapi_v1.py:56-56
Timestamp: 2026-04-20T15:09:45.119Z
Learning: In `src/app/endpoints/rlsapi_v1.py`, treat the line `_get_rh_identity_context = get_rh_identity_context` as an intentional temporary backward-compatibility shim (introduced for PR `#1548`, Splunk HEC telemetry work). Do not flag it as dead/unnecessary/unused code during review until the planned part 3 is merged and the responses endpoint is fully wired up such that no tests or external consumers reference the underscore-prefixed name.
Applied to files:
.feature-design.config.local.example.gitignore
🪛 LanguageTool
docs/contributing/templates/spike-template.md
[grammar] ~91-~91: Ensure spelling is correct
Context: ...ightspeed Core e2e engineer, I want the behave feature files for TODO feature scenario...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
docs/contributing/howto-run-a-spike.md
[grammar] ~117-~117: Ensure spelling is correct
Context: ... is the e2e kickoff Story** — write the behave .feature files for the feature, no s...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
docs/contributing/templates/spec-doc-template.md
[grammar] ~146-~146: Ensure spelling is correct
Context: ...ure lands behind a flag. ### Runbook / oncall implications What oncall needs to know...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~148-~148: Ensure spelling is correct
Context: ...### Runbook / oncall implications What oncall needs to know; new alerts, new failure ...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
docs/design/conversation-compaction/conversation-compaction-spike.md
[grammar] ~183-~183: Ensure spelling is correct
Context: ...ightspeed Core e2e engineer, I want the behave feature files for conversation-compacti...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[style] ~445-~445: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...njection as marked conversation item. - Test additive summarization (multiple compac...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~446-~446: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ization (multiple compaction cycles). - Test per-conversation blocking lock behavior...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
🪛 markdownlint-cli2 (0.22.1)
.claude/commands/spike-finalize.md
[warning] 1-1: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
[warning] 87-87: Multiple spaces after blockquote symbol
(MD027, no-multiple-space-blockquote)
[warning] 88-88: Multiple spaces after blockquote symbol
(MD027, no-multiple-space-blockquote)
docs/contributing/howto-organize-poc-output.md
[warning] 94-94: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
docs/design/conversation-compaction/conversation-compaction-spike.md
[warning] 181-181: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
[warning] 231-231: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 287-287: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 455-455: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (14)
docs/contributing/templates/spike-pr-template.md (1)
28-34: LGTM!.gitignore (1)
199-201: LGTM!.claude/commands/spec-doc.md (1)
23-29: LGTM!.feature-design.config.local.example (1)
1-32: LGTM!docs/contributing_guide.md (2)
155-159: LGTM!
169-173: LGTM!docs/contributing/feature-design.config (1)
1-178: LGTM!.claude/commands/spike-finalize.md (1)
1-104: LGTM!docs/contributing/templates/spike-template.md (1)
1-238: LGTM!docs/contributing/howto-write-a-spec-doc.md (3)
9-15: LGTM!
42-59: LGTM!
64-66: LGTM!.claude/commands/spike.md (1)
8-31: LGTM!Also applies to: 41-55, 56-98
docs/contributing/howto-run-a-spike.md (1)
11-18: LGTM!Also applies to: 39-43, 99-124, 213-224, 233-244
Comment on lines
+94
to
+99
| ``` | ||
| poc-results/ | ||
| ├── README.md # one report for the whole spike | ||
| ├── run-5-queries/ | ||
| └── run-50-queries/ | ||
| ``` |
Contributor
There was a problem hiding this comment.
Add a language identifier to the fenced block.
The code fence at Line 94 has no language tag (MD040). Use text for the directory tree block to keep markdownlint clean.
Suggested fix
-```
+```text
poc-results/
├── README.md # one report for the whole spike
├── run-5-queries/
└── run-50-queries/</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
```suggestion
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 94-94: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/contributing/howto-organize-poc-output.md` around lines 94 - 99, The
markdown fenced code block showing the directory tree in the
docs/contributing/howto-organize-poc-output.md file is missing a language
identifier (MD040); update the fenced block that contains the poc-results/ tree
to use ```text as the opening fence so the snippet is explicitly marked as plain
text and markdownlint passes.
Comment on lines
+146
to
+149
| ### Runbook / oncall implications | ||
|
|
||
| What oncall needs to know; new alerts, new failure modes, recovery | ||
| procedures. |
Contributor
There was a problem hiding this comment.
Use “on-call” instead of “oncall” for standard terminology.
At Line 146 and Line 148, prefer hyphenated “on-call” for consistency with common ops/docs terminology.
🧰 Tools
🪛 LanguageTool
[grammar] ~146-~146: Ensure spelling is correct
Context: ...ure lands behind a flag. ### Runbook / oncall implications What oncall needs to know...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~148-~148: Ensure spelling is correct
Context: ...### Runbook / oncall implications What oncall needs to know; new alerts, new failure ...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/contributing/templates/spec-doc-template.md` around lines 146 - 149,
Update the header and any occurrences of the term to use the hyphenated form
"on-call" for consistency: change the header "### Runbook / oncall implications"
to "### Runbook / on-call implications" and replace the inline phrase "What
oncall needs to know; new alerts, new failure modes, recovery procedures." with
"What on-call needs to know; new alerts, new failure modes, recovery
procedures." (search for "oncall" in this section to ensure all instances are
updated).
Comment on lines
+230
to
+244
| **Agentic tool instruction**: | ||
| ```text | ||
| Read "Acceptance Criteria" and the relevant decisions sections in | ||
| docs/design/conversation-compaction/conversation-compaction.md and this | ||
| spike doc. | ||
| Do NOT read the other JIRAs' scope sections or the implementation code | ||
| while authoring; the point of this ticket is to produce feature files | ||
| uncontaminated by implementation detail. | ||
| Key files to create: tests/e2e/features/conversation-compaction-*.feature | ||
| plus additions to tests/e2e/test_list.txt. Do NOT create step | ||
| definitions in tests/e2e/features/steps/. | ||
| To verify: `uv run behave --dry-run tests/e2e/features/conversation-compaction-*.feature` | ||
| parses successfully; `uv run make test-e2e` still green with the new | ||
| scenarios reported as undefined. | ||
| ``` |
Contributor
There was a problem hiding this comment.
Normalize fenced blocks (blank lines + language tags).
These blocks trigger markdownlint (MD031, MD040): missing blank lines around fences and missing language on at least one fence.
Suggested fix pattern
**Agentic tool instruction**:
+
-```text
+```text
...
```diff
-```
+```text
Read the "Architecture" section in
...
To verify: run pytest tests/integration/ -k compaction and confirm all pass.
</details>
Also applies to: 286-297, 455-460
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.22.1)</summary>
[warning] 231-231: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @docs/design/conversation-compaction/conversation-compaction-spike.md around
lines 230 - 244, Several fenced code blocks in the markdown (notably the
"Agentic tool instruction" fenced examples and the other examples containing
"Read the "Architecture" section..." and the short text blocks) lack
surrounding blank lines and/or explicit language tags, which triggers
markdownlint MD031/MD040; fix by adding a blank line before and after each
fenced block and ensure each fence begins with a language tag (e.g., ```text) so
all fenced blocks are separated from surrounding text and explicitly labeled;
apply the same normalization to the other similar fenced blocks in the document.
</details>
<!-- fingerprinting:phantom:triton:hawk -->
<!-- d98c2f50 -->
<!-- This is an auto-generated comment by CodeRabbit -->
…compaction spike doc LCORE-1675 was filed under LCORE-1631 (Implement conversation compaction) after the original spike but was never reflected in the spike doc's Proposed JIRAs section. It satisfies the "documentation" category required by the howto-run-a-spike's "ensure all four categories are covered" guidance (implementation, integration tests, e2e tests, documentation). Adds a stub for LCORE-1675 at the end of the Proposed JIRAs section, with title, description, scope, acceptance criteria, and agentic tool instruction matching the body filed in JIRA. After this commit, all 10 children currently filed under LCORE-1631 are represented in the spike doc: - LCORE-1673, LCORE-2230 (e2e: kickoff Story + step-defs Task) - LCORE-1569..LCORE-1573 (implementation chain) - LCORE-1574 (integration tests) - LCORE-1575 (UI team coordination) - LCORE-1675 (documentation, NEW addition) Status changes since filing (LCORE-1569/1570 Closed, LCORE-1571/1572 In Progress) are deliberately NOT reflected — the spike doc tracks the plan, not execution status; the JIRA tickets are the source of truth for status. The spec doc (conversation-compaction.md) was checked and only references LCORE-1311 (feature) and LCORE-1314 (spike); no stale ticket references there.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Refactor of the feature design process (spikes, spec docs, JIRA filing) based on team's feedback and based on spikes I've done.
Foundation: two-tier config
docs/contributing/feature-design.config— team-policy conventions (~50 settings across paths, branching, doc structure, decision presentation, PoC behavior, JIRA conventions, reviewer defaults, finalize behavior, output style, config-application UX). Read by/spike,/spec-doc,/spike-finalize. Includes a newremind_about_google_doc_after_mergesetting..feature-design.config.local.example→.feature-design.config.local(gitignored) — per-developer overrides. Sparse subset of the team file.if_applicablealongsideyes/nofor include flags. Means: the agent decides whether to include based on whether the feature actually has the concern (e.g.,include_security_considerations = if_applicable).Templates
templates/spike-template.md: three audience sections (Strategic / Technical / Stakeholder; Stakeholder isif_applicable); confidence required per recommendation; required Out-of-scope section; e2e kickoff Story (write.featurefiles, no implementation) and step-definitions Task counterpart pre-filled as the first two proposed JIRAs; newif_applicablesections for PoC findings, incidental findings, proposed incidental JIRAs, external input needed, glossary.templates/spec-doc-template.md: new always-on Acceptance test surface section (maps R1..Rn → observable behaviors; feeds the e2e-kickoff JIRA's feature files); 12-item Aspect-specific concerns group, allif_applicable(Latency/Cost, Observability, Capacity planning, Failure modes, Security, Migration/backcompat, Telemetry/data privacy, Feature flags/rollout, Runbook/oncall, Internationalization, API versioning, Rate limiting/quotas); architecture sub-sections markedif_applicable; Open Questions traceability requirement (each item must trace back to its origin).Howtos
howto-organize-poc-output.mdrewritten from a rigid numbered-file scheme (which fit the conversation-compaction PoC but not code-PoCs) to principles, with two illustrative shapes (code PoC vs data/experimental). No prescribed filenames.howto-run-a-spike.md: Configuration paragraph, three-audience guidance, confidence and Out-of-scope requirements, e2e-kickoff convention, new step 11 (Finalize after merge) pointing at/spike-finalize, updated checklist.howto-write-a-spec-doc.md: Configuration paragraph; documents the new Acceptance test surface and aspect-specific concerns sections; Open Questions traceability.Skills
/spike(.claude/commands/spike.md): reads both config files at start; announces config files loaded, actively-honored non-default settings, and items changed since last session (perconfig_announcement_at_start = notable); maintains a state file at.claude/feature-design.last-seenfor change detection; honorson_dirty_working_tree(defaultask— describes the situation and asks about worktree / move-aside / stop / proceed); honorsdecision_presentation_cadence(defaultmixed); includes the e2e kickoff Story + step-definitions Task as the first two proposed JIRAs; usesTaskCreate/TaskUpdatefor spike phase tracking; reminds about/spike-finalizeat PR-open time./spike-finalize(.claude/commands/spike-finalize.md, new): replacesLCORE-????placeholders with real keys fromjiras/metadata; verifies the spike doc and spec doc don't drift on resolved decisions; greps for orphanLCORE-????references; checkspoc-results/was removed before merge; reminds the user to create Google Docs versions of the spike + spec docs (perremind_about_google_doc_after_merge).Guide
docs/contributing_guide.md: adds step 6 (/spike-finalize) to the Feature design process flow; points at the new config files.Type of change
Tools used to create PR
Identify any AI code assistants used in this PR (for transparency and review context)
Related Tickets & Documents
Checklist before requesting a review
Testing
This PR changes only documentation, configuration files, and Claude Code skill definitions (Markdown files under
.claude/commands/). No source code paths are affected; no unit or integration tests apply.Summary by CodeRabbit
Documentation
Chores