LCORE-1736 feature design process improvements#1695
Open
max-svistunov wants to merge 5 commits intolightspeed-core:mainfrom
Open
LCORE-1736 feature design process improvements#1695max-svistunov wants to merge 5 commits intolightspeed-core:mainfrom
max-svistunov wants to merge 5 commits intolightspeed-core:mainfrom
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
|
Caution Review failedFailed to post review comments 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 |
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
Release Notes
Documentation
Chores