Skip to content

[Feature]: Preset strategy to replace one section of a template #5421

Backlog

Description

@alfredoperez

Problem Statement

A preset can change a template in four ways today: replace, prepend, append and wrap. None of them can change one section in the middle of a template. To change only ## User Scenarios & Testing in spec-template.md, a preset has to replace the whole file. That copy then stops picking up upstream changes to every other section, and it stops composing with other presets that touch the same template.

Follow-up to discussion #5326, where @mnriem asked for the cases and a fuller write-up.

Proposed Solution

A fifth template strategy, replace-section, with a section field naming the heading:

provides:
  templates:
    - type: "template"
      name: "spec-template"
      file: "templates/outcomes.md"
      strategy: "replace-section"
      section: "User Scenarios & Testing *(mandatory)*"

The file holds the new body of that section. The rules:

  1. Find the section by its heading text. Match the text after the # marks exactly, ignoring surrounding whitespace. Any heading level counts.
  2. Keep the heading line. Replace only the body, from after the heading to the next heading of the same or higher level, or the end of the file.
  3. Exactly one match, or fail. If no heading matches, or more than one does, the preset fails with an error that lists the template's headings. A renamed or duplicated section fails loudly instead of being appended or guessed at.
  4. Ignore headings inside fenced code blocks.
  5. Compose like the other strategies. It runs on the resolved lower-priority content, the same base wrap uses, so two presets can each replace a different section of the same template. Like append, prepend and wrap, it needs a lower replace base.
  6. Templates only at first. Commands and scripts keep the strategies they have.

In the code, this looks like one more branch in the composition loop of PresetResolver.resolve_content, replace-section added to VALID_PRESET_STRATEGIES, and manifest validation requiring section when the strategy is replace-section.

Alternatives Considered

  • replace the whole template. This works today, but the copy drifts from upstream and blocks other presets from composing on that template.
  • Marker comments in the core templates (<!-- section:stories -->). They're more precise, but every core template would need markers, and a project's hand-edited template would lose them. Headings already exist, and they're what people and models use to find their way around a template.
  • wrap with a hand-written copy of the other sections. Same drift problem as replace.

Component

Spec templates (BDD, Testing Strategy, etc.)

Use Cases

These come from SpecKit Companion, which uses this rule in its own template renderer:

  1. Spec: replace ## User Scenarios & Testing with observable outcomes (no P1/P2/P3 stories) for small changes, or with EARS-style numbered requirements (WHEN/THEN/SHALL) that tasks can cite by ID.
  2. Plan: a team's own ## Technical Context block with its stack's fields, and every other section stock.
  3. Tasks: replace ## Notes to rule out tasks an agent can't do (UAT, deploy, comms), or the format section so every task says how to verify itself.

Acceptance Criteria

  • A preset with strategy: "replace-section" and section: "<heading>" replaces only that section's body in the resolved template, and keeps the heading line.
  • Every other section of the template comes out the same as without the preset.
  • The section ends at the next heading of the same or higher level, so its subsections are replaced with it.
  • Zero or more than one matching heading fails with an error that names the section and lists the template's headings.
  • Headings inside fenced code blocks are not matched.
  • Two presets replacing different sections of one template both apply, in priority order.
  • Manifest validation rejects replace-section without section, and rejects it on commands and scripts.
  • The preset docs (developing.md, api.md) describe the strategy.

Additional Context

A working version is on my fork, not opened as a PR: full diff against main (branch feat/replace-section-strategy). It covers the CLI resolver, manifest validation, the bash/PowerShell/Python runtime scripts (so feature creation gives the same output as the CLI), the artifact listings, docs and tests. I'm happy to open it as a PR if this direction is agreed.

SpecKit Companion's version of this is replace_section in apps/speckit-extension/scripts/template_render.py in alfredoperez/speckit-companion, with tests. It currently takes the first of two matching headings. The "exactly one match" rule above is stricter, and I'd change ours to match.

AI Disclosure

  • Issue text: drafted with Claude Code (Claude Opus 5.5, default settings, interactive under my supervision) after reading the spec-kit preset resolver and docs. I reviewed and edited it before posting.
  • Linked branch: implemented with Claude Code (Claude Opus 5.5, default settings) in agent mode running autonomously, following a spec I wrote and reviewed. Covers code generation, tests and docs. It's a proof of concept for this discussion, not a PR.

Activity

  1. added
    triage-nice-to-haveVerdict: evidence-backed fix or greenlit feature — land after review
    feature-assessRun the Spec Kit idea-assessment pipeline on this feature request
    on Nov 13, 2026
  2. github-actions commented on Nov 16, 2026

    @github-actions
    Contributor

    Feature assessment — replace-template-section · Stage 1/5: Intake

    Idea Intake: Replace One Template Section in Presets

    Idea (as captured)

    “A preset can change a template in four ways today: replace, prepend, append and wrap. None of them can change one section in the middle of a template. To change only ## User Scenarios & Testing in spec-template.md, a preset has to replace the whole file.”

    Proposal: add a fifth strategy, replace-section, with a required section field naming the heading. Replace only the heading’s body (keep the heading line), stop at the next heading of the same or higher level, fail if zero or multiple matches, ignore headings inside fenced code blocks, and allow composition with other strategies on the same template. Scope initial support to templates (not commands/scripts). The issue includes acceptance criteria, examples, and implementation pointers (PresetResolver.resolve_content, strategy validation, and docs updates).

    Additional context in the issue points to a proof-of-concept branch and related prior art in a companion project.

    Restated

    The request is to let presets target and replace a specific markdown section inside a template instead of replacing the entire template file. The goal is to preserve upstream compatibility and allow multiple presets to compose safely when they modify different sections.

    Origin & Context

    First-Glance Unknowns

    • [NEEDS CLARIFICATION: How many real-world preset users currently need section-level template customization, and across which templates?]
    • [NEEDS CLARIFICATION: Should heading matching be exact-string only, or should normalized forms (for example trailing *(mandatory)*) be supported?]
    • [NEEDS CLARIFICATION: Should matching be case-sensitive, and how should duplicate heading text at different levels be surfaced in errors?]
    • [NEEDS CLARIFICATION: Must runtime script resolvers (bash/PowerShell/Python) also implement identical section replacement semantics in the first release?]

    Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #5421 · copilot · gpt53codex · 58.8 AIC · ⌖ 0.696 AIC · ⊞ 27.7K · ◷

  3. github-actions commented on Nov 16, 2026

    @github-actions
    Contributor

    Feature assessment — replace-template-section · Stage 2/5: Research

    Idea Research: Section-Level Template Replacement for Presets

    • Slug: replace-template-section
    • Created: 2026-11-16T14:43:27Z
    • Evidence confidence (overall): medium

    Users & Demand

    Prior Art

    • Spec Kit currently validates only four preset strategies (replace, prepend, append, wrap) and restricts scripts to replace/wrap, so replace-section is not currently representable in manifest validation — [source: src/specify_cli/presets/_manifest.py:30-32,256-264] (confidence: high).
    • Resolver behavior composes around a nearest lower replace base and applies prepend/append/wrap bottom-up; this is structurally compatible with adding another composition branch if semantics are well-defined — [source: src/specify_cli/presets/_resolver.py:796,809-820,888-894] (confidence: high).
    • Preset docs currently describe only the existing strategy matrix and explicitly call out the lower-replace-base rule; a new strategy would require docs/API updates to preserve contract clarity — [source: docs/presets/api.md:150-153; docs/presets/developing.md:85] (confidence: high).
    • Existing resolver tests already cover composition interactions (append/prepend/wrap and multi-preset chaining), giving a strong place to extend behavior and regression coverage for a section-targeted strategy — [source: tests/specify_cli/presets/test_resolver.py:1277,1307,1338,1371,1407] (confidence: high).
    • External prior art (SpecKit Companion) already implements heading-based section replacement (replace_section) with tests that keep heading line, replace section body and nested subsections, and fail when section is missing — [source: https://github.com/alfredoperez/speckit-companion/blob/946decfb3a597d0733f9d8cc73f4eabb40ae3a81/apps/speckit-extension/scripts/template_render.py ; https://github.com/alfredoperez/speckit-companion/blob/946decfb3a597d0733f9d8cc73f4eabb40ae3a81/apps/speckit-extension/tests/test_template_render.py] (confidence: medium).

    Market & Context

    • Teams customizing AI-authored templates generally need localized edits without forking whole upstream templates; this request aligns with that customization pattern in template-driven tooling — [source: ASSUMPTION] (confidence: low).
    • Doing nothing leaves preset authors with whole-file replacement, increasing long-term maintenance cost and reducing composability between presets touching one template — [source: https://github.com/[Feature]: Preset strategy to replace one section of a template #5421] (confidence: medium).

    Data & Constraints

    • Contract and runtime constraints to respect:
      • Strategy names are validated in manifest parsing; adding a strategy requires validator and error-message updates — [source: src/specify_cli/presets/_manifest.py:30-32,256-264] (confidence: high).
      • Composition assumes either top-layer replace or a discovered lower replace base; section-level replacement should remain consistent with this model — [source: src/specify_cli/presets/_resolver.py:796,809-820] (confidence: high).
      • Docs are explicit API surface and must stay synchronized when strategy capabilities change — [source: docs/presets/api.md:150-153; docs/presets/developing.md:85] (confidence: high).
    • No legal/compliance blockers were identified from repository artifacts for this capability class — [source: ASSUMPTION] (confidence: low).

    Evidence Against the Idea

    Gaps & Open Questions

    • [NEEDS CLARIFICATION: Required normalization rules for heading matching (for example treatment of *(mandatory)*, case sensitivity, and internal whitespace).]
    • [NEEDS CLARIFICATION: Error contract for duplicate headings — should output include all headings, matched heading count, and exact candidate list formatting?]
    • [NEEDS CLARIFICATION: First-release scope parity across resolver/runtime paths (Python, bash, PowerShell) and whether any path can be deferred.]
    • [NEEDS CLARIFICATION: Minimum evidence threshold expected by maintainers for “go” on template-strategy additions (single adopter vs broader demand).]

    Sources

    Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #5421 · copilot · gpt53codex · 58.8 AIC · ⌖ 0.696 AIC · ⊞ 27.7K · ◷

  4. github-actions commented on Nov 16, 2026

    @github-actions
    Contributor

    Feature assessment — replace-template-section · Stage 3/5: Problem

    Problem Definition: Preset Authors Cannot Safely Customize Single Template Sections

    • Slug: replace-template-section
    • Created: 2026-11-16T14:43:27Z
    • Inputs used: intake.md + research.md

    Problem Statement

    Preset authors who need to customize one section inside a stock template must currently replace the entire template file, which breaks composability with other presets and increases drift from upstream template updates. This creates recurring maintenance overhead and raises the risk of inconsistent template outcomes as templates evolve.

    Affected Users & Stakeholders

    • Users: Preset authors and teams maintaining customized Spec Kit workflows — forced into whole-template forks for section-level changes.
    • Users: AI-agent operators consuming generated specs/plans/tasks — may receive inconsistent output shape when multiple presets cannot compose cleanly.
    • Stakeholders: Spec Kit maintainers — responsible for composition correctness, manifest contract stability, and docs/runtime parity.
    • Stakeholders: Extension/preset ecosystem contributors — need predictable, composable customization primitives for distribution.

    Goals

    • Enable section-scoped template customization without requiring full-template replacement.
    • Preserve predictable composition behavior when multiple presets target different parts of the same template.
    • Reduce long-term drift/maintenance burden caused by copying and maintaining full upstream templates.
    • Keep failure modes explicit (loud failures) when section targeting is ambiguous or invalid.

    Non-Goals

    • Redesigning overall preset composition architecture.
    • Introducing full markdown-AST editing or arbitrary text patch semantics.
    • Expanding first-release scope to command/script section replacement unless separately justified.
    • Defining implementation design/API details beyond problem framing.

    Success Metrics

    • Preset authors can customize intended template sections without copying untouched sections (baseline: currently unknown in repo telemetry; known pain in [Feature]: Preset strategy to replace one section of a template #5421).
    • Composition conflict/drift reports related to whole-template replacement decrease after rollout (baseline: [NEEDS CLARIFICATION: no measured baseline in current artifacts]).
    • Ambiguous/missing section targets fail explicitly rather than silently producing incorrect output (baseline: existing strategy model already enforces explicit strategy validity).
    • Documentation accurately describes strategy behavior and constraints across API + developing guides (baseline: docs currently list only four strategies).

    Cost of Inaction

    If no section-level primitive is added, teams continue using whole-file replacement for localized customizations, making upstream template improvements harder to adopt and reducing compatibility among presets that touch the same template. This sustains avoidable maintenance cost and ecosystem friction.

    Open Questions

    • [NEEDS CLARIFICATION: What normalization semantics should define “same heading” across markdown variants and decoration such as *(mandatory)*?]
    • [NEEDS CLARIFICATION: What minimum user-signal threshold is required to justify adding a new preset strategy to the public contract?]
    • [NEEDS CLARIFICATION: Which runtime paths must ship in lockstep for parity (CLI resolver, bash, PowerShell, Python helpers)?]
    • [NEEDS CLARIFICATION: Are there existing templates with duplicate heading text that would make strict single-match behavior operationally noisy?]

    Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #5421 · copilot · gpt53codex · 58.8 AIC · ⌖ 0.696 AIC · ⊞ 27.7K · ◷

  5. github-actions commented on Nov 16, 2026

    @github-actions
    Contributor

    Feature assessment — replace-template-section · Stage 4/5: Concept

    Concept: Add a Section-Scoped Preset Strategy

    • Slug: replace-template-section
    • Created: 2026-11-16T14:43:27Z
    • Recommended option: Option B — Template-only replace-section with strict matching

    Options

    Option A — Keep Existing Strategies (Do Nothing)

    • Sketch: Continue requiring whole-template replace for localized edits, with guidance to minimize drift manually.
    • Appetite: small
    • Trade-offs: No new API surface or implementation risk, but preserves known composability and maintenance pain.
    • Rabbit holes: Ecosystem fragmentation as each preset forks templates differently; recurring support burden.

    Option B — Template-only replace-section with Strict Heading Match

    • Sketch: Introduce a new template strategy that replaces only one named section body while preserving surrounding content and current composition behavior.
    • Appetite: medium
    • Trade-offs: Solves the reported pain directly and composes better than full-file replacement; adds contract complexity and requires tight semantics for matching and failure cases.
    • Rabbit holes: Heading normalization edge cases, duplicate headings, and parity across all template resolution paths.

    Option C — Rich Marker/AST-Based Section Editing

    • Sketch: Add a more expressive customization model (markers or markdown-aware editing) for robust structural edits beyond heading-based replacement.
    • Appetite: large
    • Trade-offs: Higher flexibility and future-proofing, but materially larger design/testing/documentation surface and slower delivery.
    • Rabbit holes: Parser behavior differences, migration model, backward compatibility, and major maintenance overhead.

    Recommendation

    Recommend Option B. It is the smallest concept that directly addresses the identified user pain while preserving the existing composition mental model (replace base plus composition layers). It offers meaningful value over inaction without the large complexity jump of a generalized editing system.

    Out of Scope (for the recommended option)

    • Command/script section replacement in first release.
    • General markdown-AST or regex patching semantics.
    • Auto-healing ambiguous heading matches (strict fail remains preferred).
    • Broader preset-composition redesign.

    Assumptions to Validate

    • The heading-matching contract can be specified clearly enough to avoid surprising behavior.
    • Duplicate heading sections are uncommon enough that strict single-match failure is acceptable.
    • The implementation can preserve behavior parity across all template-resolution entry points.
    • Maintainers accept medium confidence demand evidence (targeted but not broad) for this strategy addition.

    Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #5421 · copilot · gpt53codex · 58.8 AIC · ⌖ 0.696 AIC · ⊞ 27.7K · ◷

  6. github-actions commented on Nov 16, 2026

    @github-actions
    Contributor

    Feature assessment — replace-template-section · Stage 5/5: Decision — verdict needs-clarification

    Decision: Replace-Section Strategy for Preset Templates

    • Slug: replace-template-section
    • Decided: 2026-11-16T14:43:27Z
    • Verdict: needs-clarification
    • Artifacts reviewed: intake.md | research.md | problem.md | concept.md

    Scorecard

    Criterion Rating Justification
    Problem validity strong The current strategy set forces whole-template replacement for localized edits, with clear composability and drift pain documented in the issue and aligned with current resolver/docs contracts.
    Evidence strength weak Evidence is detailed but narrow (primarily one contributor report plus proof branch/prior art); broad multi-team demand and quantitative frequency are not established.
    Value vs. inaction adequate If adopted, section-level edits likely reduce drift and improve composition; doing nothing preserves known friction.
    Feasibility / appetite adequate A medium-appetite concept exists that fits current composition patterns, but exact semantics and parity scope remain unresolved.
    Strategic fit adequate The capability aligns with Spec Kit’s customization/preset ecosystem direction and existing composition APIs.
    Risk posture weak Key risks (heading ambiguity, duplicate matches, parity across resolution paths) are identified but not yet fully bounded with agreed acceptance semantics.

    Verdict & Rationale

    Verdict: needs-clarification. The problem is valid and a credible medium-size concept exists, but evidence strength is currently too narrow and key behavioral semantics are still open. Under the decision rules, this is not yet a defensible go: the proposal should return for targeted clarification on demand breadth and contract edge cases before handoff to specification.

    If needs-clarification

    • Blocking questions:
      • [NEEDS CLARIFICATION: What exact heading-match normalization contract is required (decoration stripping, case sensitivity, whitespace normalization)?]
      • [NEEDS CLARIFICATION: What user-signal threshold (number/type of adopters or linked use cases) is required for adding a new preset strategy to public API?]
      • [NEEDS CLARIFICATION: What parity scope is mandatory in first release (CLI resolver only vs CLI + generated bash/PowerShell/Python resolution paths)?]
      • [NEEDS CLARIFICATION: What exact duplicate-heading error contract should be guaranteed to users/tools?]
    • Revisit stage: research

    If go — Handoff to /speckit-specify

    Not applicable for needs-clarification.

    Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #5421 · copilot · gpt53codex · 58.8 AIC · ⌖ 0.696 AIC · ⊞ 27.7K · ◷

  7. mnriem commented on Nov 16, 2026

    @mnriem
    Collaborator

    Maintainer clarification for reassessment:

    I accept the use case and maintenance benefit as sufficient justification to proceed into specification: targeted replacement avoids copying and maintaining an entire template or command just to change one section. Broader adoption counts are not a prerequisite for accepting this direction.

    The agreed scope and behavior are:

    • Support section replacement in both templates and Markdown commands. Editing sections of executable scripts is out of scope.
    • Select sections using GitHub-style heading anchors, such as #technical-context: lowercase with hyphens rather than underscores, following GitHub heading-anchor normalization rather than literal heading-text matching. Pin down the exact normalization contract during specification.
    • Require exactly one matching section. Missing or ambiguous matches must fail explicitly with diagnostics identifying the requested section and available headings, so the user can update the Markdown or selector. Do not silently select the first duplicate or automatically disambiguate duplicates with numbered suffixes.
    • Preserve the heading and replace only its body, including nested subsections, up to the next heading of the same or higher level or the end of the file. Ignore headings inside fenced code blocks and preserve content outside the selected section.
    • Require equivalent behavior across the CLI resolver and Bash, PowerShell, and Python runtime resolution paths from the first release, including Windows PowerShell 5.1 compatibility.
    • Retain the existing lower-priority replacement-base and composition model. Generalized Markdown editing and broader composition redesign remain out of scope.

    Please reassess against these decisions. The accepted direction is a bounded feature worth specifying, not approval of the linked implementation; exact anchor semantics and composition edge cases should be resolved in the specification.

    AI disclosure: Posted on behalf of @mnriem using GitHub Copilot, model GPT-6.1 Sol (gpt-6.1-sol), default settings in an interactive session with user-directed scope and authorization. AI drafted this clarification from the discussion; no implementation or validation was performed.

  8. added
    feature-assessRun the Spec Kit idea-assessment pipeline on this feature request
    and removed
    feature-assessRun the Spec Kit idea-assessment pipeline on this feature request
    on Nov 16, 2026
  9. github-actions commented on Nov 16, 2026

    @github-actions
    Contributor

    Feature assessment — replace-template-section · Stage 1/5: Intake

    Idea Intake: Replace One Template or Command Section in Presets

    Idea (as captured)

    “A preset can change a template in four ways today: replace, prepend, append and wrap. None of them can change one section in the middle of a template. To change only ## User Scenarios & Testing in spec-template.md, a preset has to replace the whole file.”

    Proposed capability: add a replace-section strategy so presets can replace only one Markdown section body while preserving the heading and all unrelated sections.

    Reassessment clarification from maintainer comment (2026-11-16): this direction is accepted for specification if scoped to Markdown templates and Markdown commands (not executable scripts), with explicit failure on missing/ambiguous matches, GitHub-style anchor-based selectors, and parity across CLI + Bash + PowerShell + Python runtime paths.

    Additional reference included by reporter: main...alfredoperez:spec-kit:feat/replace-section-strategy

    Restated

    Preset authors need a way to customize only one section of a Markdown artifact without forking the entire file. The requested behavior should compose with existing preset layering and fail explicitly when section selection is ambiguous or invalid.

    Origin & Context

    First-Glance Unknowns

    • [NEEDS CLARIFICATION: Exact heading-anchor normalization contract (GitHub-style rules, including punctuation/duplicates) for section selectors.]
    • [NEEDS CLARIFICATION: Whether one strategy name should cover both templates and commands, or whether command support should use a distinct manifest contract.]
    • [NEEDS CLARIFICATION: Exact diagnostic contract format for zero-match and multi-match failures across CLI and runtime scripts.]
    • [NEEDS CLARIFICATION: Compatibility guarantees for existing presets that currently use full-file replace or wrap workarounds.]

    Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #5421 · copilot · gpt53codex · 65.2 AIC · ⌖ 0.697 AIC · ⊞ 27.7K · ◷

  10. github-actions commented on Nov 16, 2026

    @github-actions
    Contributor

    Feature assessment — replace-template-section · Stage 2/5: Research

    Idea Research: Section-Level Markdown Replacement for Presets

    • Slug: replace-template-section
    • Created: 2026-11-16T21:52:05Z
    • Evidence confidence (overall): medium

    Users & Demand

    Prior Art

    • The current manifest and resolver support exactly four composition strategies (replace, prepend, append, wrap), with no section-targeted mode. — [source: src/specify_cli/presets/_manifest.py#L30, src/specify_cli/presets/_resolver.py#L735-L905] (confidence: high)
    • Current docs describe only those four strategies and explicitly separate script constraints (replace/wrap only), which aligns with the maintainer’s “no executable script section editing” scope. — [source: docs/presets/api.md#L139-L145] (confidence: high)
    • Runtime parity mechanisms already exist in Bash, PowerShell, and Python template-resolution paths with mirrored strategy validation, indicating an established precedent for cross-runtime behavior parity work. — [source: scripts/bash/common.sh#L734-L752, scripts/powershell/common.ps1#L651-L669, scripts/python/common.py#L363-L384] (confidence: high)
    • Existing tests cover strategy semantics and multi-preset composition chaining, which lowers risk of adding one more composition mode if backed by equivalent tests. — [source: tests/specify_cli/presets/test_resolver.py#L1277-L1407] (confidence: medium)

    Market & Context

    Data & Constraints

    • Manifest and artifact schemas currently type strategy literals as replace|wrap|prepend|append; adding a new strategy touches validation plus artifact APIs. — [source: src/specify_cli/presets/_manifest.py#L30-L31, src/specify_cli/artifacts/mcp_info.py#L71, src/specify_cli/artifacts/mcp_list.py#L75, src/specify_cli/artifacts/_operation_list.py#L27] (confidence: high)
    • Scope constraint accepted by maintainer: include templates and Markdown commands; exclude executable scripts; preserve existing composition model and replacement-base behavior. — [source: issue comment 6930426794] (confidence: high)
    • Parity constraint: behavior must be equivalent across CLI resolver and generated Bash/PowerShell/Python runtime resolution paths (including Windows PowerShell 5.1 compatibility expectations). — [source: issue comment 6930426794; AGENTS.md PowerShell guidance] (confidence: high)

    Evidence Against the Idea

    • Demand evidence is mostly qualitative (single issue thread plus maintainer decision) and lacks broad usage metrics; this raises uncertainty on priority versus other roadmap work. — [source: issue [Feature]: Preset strategy to replace one section of a template #5421] (confidence: medium)
    • Section-selection semantics can become complex (anchor normalization, duplicates, headings in fenced blocks), creating implementation and maintenance risk if underspecified. — [source: issue [Feature]: Preset strategy to replace one section of a template #5421 acceptance criteria + maintainer clarification] (confidence: high)
    • Expanding support to both templates and commands from day one increases blast radius relative to a template-only rollout, especially under strict cross-runtime parity requirements. — [source: issue comment 6930426794; runtime strategy code paths] (confidence: medium)

    Gaps & Open Questions

    • [NEEDS CLARIFICATION: Exact canonical algorithm for GitHub-style anchor normalization and duplicate-anchor handling contract.]
    • [NEEDS CLARIFICATION: Required error message shape and whether headings list output must be deterministic/sorted.]
    • [NEEDS CLARIFICATION: Compatibility policy for existing presets if heading text/anchors drift over time.]
    • [NEEDS CLARIFICATION: Minimum required regression matrix across CLI + Bash + PowerShell + Python for release readiness.]

    Sources

    Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #5421 · copilot · gpt53codex · 65.2 AIC · ⌖ 0.697 AIC · ⊞ 27.7K · ◷

  11. github-actions commented on Nov 16, 2026

    @github-actions
    Contributor

    Feature assessment — replace-template-section · Stage 3/5: Problem

    Problem Definition: Fine-Grained Preset Customization Without Template Forking

    • Slug: replace-template-section
    • Created: 2026-11-16T21:52:05Z
    • Inputs used: intake.md + research.md + issue comments

    Problem Statement

    Preset authors who need to change one Markdown section of a template or command must currently replace or wrap larger content blocks, which increases drift from upstream defaults and reduces safe composition with other presets. This creates recurring maintenance overhead and fragile customization behavior in normal preset composition workflows.

    Affected Users & Stakeholders

    • Users: Preset authors and teams customizing Spec Kit templates/commands — they cannot target one section without taking ownership of unrelated content.
    • Users: Teams consuming shared presets — they inherit drift and merge friction when presets must fork full artifacts.
    • Stakeholders: Spec Kit maintainers — they own composition semantics, validation contracts, runtime parity, and documentation quality.
    • Stakeholders: Downstream integration maintainers (Bash/PowerShell/Python runtime paths) — they must preserve equivalent behavior across execution paths.

    Goals

    • Enable section-scoped customization for Markdown artifacts so users can change one section body without replacing entire files.
    • Preserve deterministic, explicit failure behavior when the requested section cannot be selected unambiguously.
    • Maintain composition expectations so multiple presets can still combine safely on the same artifact when targeting different sections.
    • Keep runtime behavior aligned across CLI and generated script runtimes.

    Non-Goals

    • General-purpose Markdown editing primitives beyond section-body replacement.
    • Section editing for executable scripts.
    • A broader redesign of preset composition priority or replacement-base semantics.
    • Solving all historical template drift causes outside this specific section-targeting gap.

    Success Metrics

    • A preset author can modify one specified section body while preserving untouched sections and headings (baseline: not possible with current four strategies).
    • Missing or ambiguous selectors fail with actionable diagnostics instead of silent fallback behavior (baseline: no section selector exists).
    • Equivalent outcomes are produced by CLI resolution and Bash/PowerShell/Python runtime resolution for the same preset stack (baseline: parity applies only to current strategies).
    • Documentation and validation clearly communicate where the strategy is allowed and disallowed (baseline: only four strategy values documented).

    Cost of Inaction

    If this is not addressed, users continue forking whole templates/commands for local section edits, increasing drift, review burden, and conflicts between otherwise compatible presets. Over time, that weakens maintainability of shared preset ecosystems and discourages modular customization.

    Open Questions

    • [NEEDS CLARIFICATION: Exact selector normalization and duplicate handling contract for GitHub-style anchors.]
    • [NEEDS CLARIFICATION: Required diagnostic wording/shape for zero and multiple matches.]
    • [NEEDS CLARIFICATION: Required acceptance test matrix and parity gates across CLI + Bash + PowerShell + Python.]

    Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #5421 · copilot · gpt53codex · 65.2 AIC · ⌖ 0.697 AIC · ⊞ 27.7K · ◷

  12. github-actions commented on Nov 16, 2026

    @github-actions
    Contributor

    Feature assessment — replace-template-section · Stage 4/5: Concept

    Concept: Section-Scoped Preset Composition for Markdown Artifacts

    • Slug: replace-template-section
    • Created: 2026-11-16T21:52:05Z
    • Recommended option: Option B — Bounded section-replacement strategy for templates and commands

    Options

    Option A — Template-only section replacement first

    • Sketch: Add a section-targeted strategy only for type: template, leaving commands unchanged initially. Users gain immediate relief for spec/plan/tasks template customization while command behavior remains current.
    • Appetite: small
    • Trade-offs: Lower implementation surface and faster rollout, but does not satisfy clarified scope that explicitly includes Markdown commands; risks follow-on redesign and inconsistent user mental model between templates and commands.
    • Rabbit holes: Future command parity work may require revisiting selector contracts and error wording, creating churn across docs/tests.

    Option B — Bounded section replacement for templates + Markdown commands

    • Sketch: Introduce one section-replacement strategy for Markdown artifacts (templates and commands) with explicit selector semantics, strict exactly-one-match behavior, preserved heading line, section-body replacement through same-or-higher heading boundary, fenced-code heading exclusion, and no script support.
    • Appetite: medium
    • Trade-offs: Aligns with maintainer-accepted scope and maximizes consistency for users; higher upfront complexity due to resolver/runtime parity and API/doc updates.
    • Rabbit holes: Anchor normalization edge cases, duplicate headings/anchors, and keeping error diagnostics consistent across all runtime paths.

    Option C — Do nothing (continue with replace/wrap workarounds)

    • Sketch: Keep current four strategies and advise users to use full-file replace or wrap patterns for section-level customization intent.
    • Appetite: small
    • Trade-offs: No implementation risk now, but preserves known drift/composability pain and contradicts maintainer decision that the problem is worth specifying.
    • Rabbit holes: Ongoing support burden from workaround complexity and repeated future requests for finer-grained composition.

    Recommendation

    Recommend Option B. It directly addresses the defined problem, matches the maintainer’s accepted reassessment scope, and preserves existing composition foundations while adding targeted capability where users need it. The increased implementation surface is manageable if the specification first locks selector normalization, ambiguity handling, and parity test requirements.

    Out of Scope (for the recommended option)

    • Editing executable scripts by section.
    • Generalized Markdown AST transforms or arbitrary text patch operations.
    • Redesigning preset priority resolution/composition ordering.
    • Non-Markdown artifact mutation strategies.

    Assumptions to Validate

    • GitHub-style anchor normalization can be specified unambiguously enough for deterministic cross-runtime behavior.
    • Existing composition architecture can incorporate section replacement without breaking current strategy guarantees.
    • Cross-runtime parity tests can be expanded to cover section matching boundaries and fenced-code exclusions without excessive maintenance cost.

    Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #5421 · copilot · gpt53codex · 65.2 AIC · ⌖ 0.697 AIC · ⊞ 27.7K · ◷

  13. github-actions commented on Nov 16, 2026

    @github-actions
    Contributor

    Feature assessment — replace-template-section · Stage 5/5: Decision — verdict go

    Decision: Add Bounded Section-Replacement Strategy for Markdown Artifacts

    • Slug: replace-template-section
    • Decided: 2026-11-16T21:52:05Z
    • Verdict: go
    • Artifacts reviewed: intake.md + research.md + problem.md + concept.md + issue comments

    Scorecard

    Criterion Rating Justification
    Problem validity strong The pain is concrete: users cannot safely target one section without full-file replacement or broad wrappers, creating drift/composition cost.
    Evidence strength adequate Evidence includes a detailed issue, explicit maintainer clarification accepting bounded scope, and direct code/doc constraints; broad quantitative demand data is limited.
    Value vs. inaction strong Inaction preserves known drift and composability overhead for preset authors and consumers, while scoped capability directly reduces that burden.
    Feasibility / appetite adequate Existing resolver/runtime architecture already supports compositional strategies and parity patterns; adding one bounded strategy is credible at medium appetite with clear spec work.
    Strategic fit strong The proposal aligns with Spec Kit’s composable preset model and was explicitly accepted as “worth specifying” by maintainer clarification.
    Risk posture adequate Key risks (anchor normalization, ambiguity handling, parity consistency) are known and can be mitigated by precise specification and parity tests.

    Verdict & Rationale

    Verdict: go. The problem is real and materially affects maintainability/composability, the inaction cost is clear, and a bounded concept exists that fits project direction. Evidence is sufficient for specification (though not yet implementation-ready), and the remaining uncertainty is about exact selector/error contracts rather than whether the capability should exist.

    If needs-clarification

    • Not applicable for this verdict.

    If go — Handoff to /speckit-specify

    • Problem: Preset authors need section-level Markdown customization without full-file forks that drift and block composition.
    • Chosen approach: Add a bounded section-replacement strategy for templates and Markdown commands (no scripts) with strict exactly-one-match behavior and explicit diagnostics.
    • In scope / out of scope: In scope is selector-based section body replacement with preserved heading and fenced-code safeguards; out of scope is executable script section editing and general Markdown editing redesign.
    • Success metrics: Section-targeted replacements preserve untouched content, ambiguous/missing matches fail explicitly, and CLI/Bash/PowerShell/Python produce equivalent outputs.
    • Carried-forward open questions:
      • [NEEDS CLARIFICATION: Canonical GitHub-style anchor normalization contract, including duplicate-anchor semantics.]
      • [NEEDS CLARIFICATION: Exact diagnostic payload/text requirements for no-match and multi-match errors.]
      • [NEEDS CLARIFICATION: Required parity/regression test matrix across CLI + Bash + PowerShell + Python, including Windows PowerShell 5.1 expectations.]

    Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #5421 · copilot · gpt53codex · 65.2 AIC · ⌖ 0.697 AIC · ⊞ 27.7K · ◷

  14. added
    feature-goFeature assessment verdict: go — ready to hand off to /speckit.specify
    on Nov 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    feature-assessRun the Spec Kit idea-assessment pipeline on this feature requestfeature-goFeature assessment verdict: go — ready to hand off to /speckit.specifytriage-nice-to-haveVerdict: evidence-backed fix or greenlit feature — land after review

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions