Activity

1. harsha09

   added

   enhancement

   on Aug 17, 2026
2. mnriem

   added

   feature-assessRun the Spec Kit idea-assessment pipeline on this feature requestRun the Spec Kit idea-assessment pipeline on this feature request

   on Aug 19, 2026
3. github-actions commented on Aug 19, 2026

   

   github-actionsbot

   on Aug 19, 2026 – with GitHub Actions

   Contributor

   More actions

   Feature assessment — structured-ids-context-packs · Stage 1/5: Intake

   Idea Intake: Stop grep-based spec alignment, structured IDs + context packs

   • Slug: structured-ids-context-packs
   • Created: 2026-08-19
   • Source: GitHub issue [Feature]: Stop grep-based spec alignment, structured IDs + context packs #4164 (pasted text)
   • Type: improvement

   Idea (as captured)

   Problem Statement

   I'm frustrated when a product change (especially a UI change) has to be folded into an existing feature. Agents find related work by grepping similar wording in spec.md, plan.md, and tasks.md. After a reword "charge on Pay" vs "show a confirm modal" the live AC/FR is often not retrieved, so another /speckit.specify pass or a manual edit adds a new requirement instead of updating the existing one.

   The result is two live lines for the same behavior, or two live lines that contradict each other. /speckit.analyze is supposed to catch duplicates and conflicts, but it only reports what the model loaded. If the related line was never in context, the report is clean.

   Proposed Solution

   1. Structured sidecar (tasks.yaml alongside tasks.md) — each task record: id, status, story, files, covers: [US1/AC2, FR-007]. Python script is the only mutator.
   2. Complete live inventory — script emits every live FR-/AC/SC/T- for the feature; specify consults before adding; analyze builds from it; implement loads one task plus covered records.
   3. Context pack (specify context --task T014) — small JSON pack: that task + live ACs/FRs + matching plan bullets. Commands drive from pack/inventory, not whole Markdown dumps.
   4. Local per-feature recall (opt-in phase 2) — local embedding index under specs/<feature>/.index/.
   5. Classify-on-write alignment — before adding a requirement: already-true → skip; same behavior new words → edit existing; contradicts live → conflict; genuinely new → one new ID.

   Restated

   The current Spec Kit spec-alignment workflow relies on agents grepping prose in three Markdown files, which silently misses renamed or paraphrased requirements and creates duplicate or contradictory live lines. The idea is to replace that grep-based discovery with a script-owned structured inventory of requirement and task IDs, plus a focused "context pack" command, so every SDD command operates on the full live set rather than a partial token-budget slice.

   Origin & Context

   • Raised by: harsha09
   • Trigger: Practical frustration with spec alignment breaking down when UI copy changes rephrase existing requirements; /speckit.analyze not catching duplicates/conflicts reliably

   First-Glance Unknowns

   • [NEEDS CLARIFICATION: Does the proposal intend tasks.yaml to fully replace tasks.md as the writeable record, or exist alongside it as a derived artifact?]
   • [NEEDS CLARIFICATION: Which commands are in scope for Phase 1 — specify, analyze, implement only, or also tasks, plan, converge, checklist?]
   • [NEEDS CLARIFICATION: What is the backward-compatibility story for existing projects with no tasks.yaml?]
   • [NEEDS CLARIFICATION: How does the live inventory handle multi-feature projects where IDs might collide across feature directories?]
   • [NEEDS CLARIFICATION: Is the local embedding index (Phase 2) expected to be stored in-repo or excluded via .gitignore?]
   • [NEEDS CLARIFICATION: What is the target scope for "context pack" — single task, feature, or cross-feature?]

   Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4164 · 471.8 AIC · ⌖ 28.7 AIC · ⊞ 38.1K · ◷
4. github-actions commented on Aug 19, 2026

   

   github-actionsbot

   on Aug 19, 2026 – with GitHub Actions

   Contributor

   More actions

   Feature assessment — structured-ids-context-packs · Stage 2/5: Research

   Idea Research: Stop grep-based spec alignment, structured IDs + context packs

   • Slug: structured-ids-context-packs
   • Created: 2026-08-19
   • Evidence confidence (overall): medium

   Users & Demand

   • Spec Kit users who iterate on UI/product features experience alignment breakage when requirement phrasing evolves — an agent adding "confirm modal" on top of an existing "charge on Pay" requirement creates silent duplicates. — [source: issue [Feature]: Stop grep-based spec alignment, structured IDs + context packs #4164, author harsha09] (confidence: high, cited)
   • The issue is self-describing and specific — the reporter articulates a concrete failure mode (grep misses renamed requirements) with a clear symptom (two live lines for the same behavior), suggesting at least one active user hitting it in practice. — [source: issue [Feature]: Stop grep-based spec alignment, structured IDs + context packs #4164] (confidence: medium, cited)
   • No usage data or support ticket volume available to quantify prevalence across the broader user base. — [NEEDS CLARIFICATION: How many users report this? Any prior community discussion?] (confidence: low, assumption)

   Prior Art

   • Internal — analyze command's requirements inventory (templates/commands/analyze.md): The current /speckit.analyze already extracts a "requirements inventory" (FR-/SC- IDs) and builds a coverage mapping per run. However, this inventory is ephemeral — reconstructed from markdown each time — rather than a persistent shared artifact. This confirms the ID-based approach is already partially acknowledged, but no cross-command persistence exists. — [source: codebase read] (confidence: high, cited)
   • Internal — tasks format already has T-IDs and US-labels (templates/commands/tasks.md): Tasks use T001/T002 sequential IDs and [US1] story labels. There is no covers: field or tasks.yaml sidecar in the current schema. — [source: codebase read] (confidence: high, cited)
   • Internal — spec template uses FR-001 identifiers (templates/spec-template.md): FRs already carry structured IDs in specs; they are just not shared across commands via a script-owned persistent store. — [source: codebase read] (confidence: high, cited)
   • Internal — check-prerequisites script loads entire markdown files and outputs FEATURE_DIR; no structured sidecar or JSON inventory is produced. — [source: scripts/bash/check-prerequisites.sh, codebase read] (confidence: high, cited)
   • External — Linear/JIRA/GitHub Issues all maintain persistent structured issue IDs that tools can query. The proposal applies this well-understood pattern to per-feature spec artifacts. — [source: general knowledge, ASSUMPTION] (confidence: medium, assumption)
   • No prior closed Spec Kit issues or merged PRs found in this codebase addressing structured ID persistence. — [source: codebase exploration] (confidence: medium, cited)

   Market & Context

   • Alternative users rely on today: manually re-running /speckit.analyze repeatedly and hoping the model loads the right context window; manually editing spec.md to remove duplicates; staying disciplined about not rewording requirements (fragile). — [source: issue [Feature]: Stop grep-based spec alignment, structured IDs + context packs #4164] (confidence: high, cited)
   • Cost of doing nothing: duplicate or contradictory live requirements accumulate silently; /speckit.implement may build against the wrong or stale requirement; trust in the SDD pipeline erodes. — [source: issue [Feature]: Stop grep-based spec alignment, structured IDs + context packs #4164, codebase analysis] (confidence: high, cited)
   • The proposal is additive — tasks.yaml alongside tasks.md, context pack as a new command — so backward compatibility is achievable but requires explicit design. — [source: codebase structure analysis] (confidence: medium, cited)

   Data & Constraints

   • Token budget pressure is real: each command currently runs check-prerequisites which emits FEATURE_DIR and outputs whole markdown files. A context pack reducing that to a focused JSON directly addresses a known LLM context window constraint. — [source: templates/commands/implement.md, templates/commands/analyze.md] (confidence: high, cited)
   • Scope is broad: the proposal spans at minimum 5 commands (specify, analyze, implement, tasks, converge), a new Python script (inventory mutator), a new file format (tasks.yaml), and an optional embedding subsystem. Phase 1 alone is medium-to-large appetite. — [source: codebase analysis] (confidence: high, cited)
   • Python script consistency: the proposal requires Python for the inventory mutator. Spec Kit already ships Python scripts (scripts/python/) alongside bash/PowerShell; this is consistent with existing architecture. — [source: scripts/python/, codebase read] (confidence: high, cited)

   Evidence Against the Idea

   • Complexity vs. benefit ratio is unclear for smaller projects: teams with few features and rarely-renamed requirements would carry the overhead of a YAML sidecar for little gain.
   • Two-format maintenance burden: keeping tasks.md and tasks.yaml in sync introduces a new failure mode — if the Python mutator is bypassed, they drift. The enforcement mechanism is agent convention, not a hard constraint.
   • Phase 2 (embeddings) adds significant complexity and storage cost with uncertain payoff — the proposal itself makes it opt-in, acknowledging this.
   • Existing analyze command already does ID-based coverage mapping per run — the gap is persistence and sharing, which might be solvable with a lighter-weight approach than a full YAML sidecar (e.g., a generated inventory section in tasks.md, or a thin JSON file just for IDs).

   Gaps & Open Questions

   • [NEEDS CLARIFICATION: What is the migration path for existing projects that have tasks.md but no tasks.yaml?]
   • [NEEDS CLARIFICATION: Who owns tasks.yaml on conflict — the human (tasks.md edit) or the script? How is drift detected and resolved?]
   • [NEEDS CLARIFICATION: Is "context pack" a new CLI subcommand, a new agent skill, or both?]
   • [NEEDS CLARIFICATION: How does multi-feature ID uniqueness work? Are IDs feature-scoped or global?]
   • [NEEDS CLARIFICATION: Phase 2 embedding index — which embedding model, and is there a privacy concern for proprietary codebases?]

   Sources

   • GitHub issue [Feature]: Stop grep-based spec alignment, structured IDs + context packs #4164, [Feature]: Stop grep-based spec alignment, structured IDs + context packs #4164 (host: github.com, policy: allowlisted)
   • Codebase reads: templates/commands/analyze.md, templates/commands/tasks.md, templates/commands/implement.md, templates/spec-template.md, scripts/bash/check-prerequisites.sh, src/specify_cli/ (local repo, no URL fetch)

   Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4164 · 471.8 AIC · ⌖ 28.7 AIC · ⊞ 38.1K · ◷
5. github-actions commented on Aug 19, 2026

   

   github-actionsbot

   on Aug 19, 2026 – with GitHub Actions

   Contributor

   More actions

   Feature assessment — structured-ids-context-packs · Stage 3/5: Problem

   Problem Definition: Stop grep-based spec alignment, structured IDs + context packs

   • Slug: structured-ids-context-packs
   • Created: 2026-08-19
   • Inputs used: intake.md | research.md

   Problem Statement

   When a Spec Kit user refines or renames a requirement mid-feature (a common occurrence in UI-heavy product work), the SDD pipeline's grep-based context loading silently misses the renamed line, causing agents to add a second live requirement instead of updating the existing one — producing duplicate or contradictory specifications that the current /speckit.analyze command cannot reliably detect because it only reports on what it happened to load.

   Affected Users & Stakeholders

   • Users: Spec Kit users iterating on product/UI features — they experience accumulating duplicate or contradictory FRs/ACs and are forced to rerun /speckit.analyze repeatedly without a reliable result.
   • Stakeholders: Spec Kit maintainers (github/spec-kit) — the reliability of the SDD pipeline is a core product promise; silent spec drift undermines that promise and trust in the toolchain.

   Goals

   • Every SDD command (at minimum: specify, analyze, implement) can consult a complete, authoritative list of live requirement and task IDs for the current feature before adding or modifying a requirement.
   • Adding a requirement is a classified write operation: duplicate → skip, paraphrase → update existing, conflict → block, genuinely new → create new ID.
   • A focused "context pack" reduces token waste (no whole-file dumps) and eliminates the missed-line failure mode from partial context windows.
   • The approach is backward-compatible: projects without the new sidecar continue to work with existing behavior.

   Non-Goals

   • Replacing tasks.md as the human-readable artifact — it remains the primary format.
   • Global or cross-feature ID namespacing beyond per-feature scoping.
   • A hosted or cloud vector store for embeddings (Phase 2 is local and opt-in).
   • Changing the Spec Kit spec/plan template formats (FR-001 naming stays).
   • Real-time sync or conflict resolution between concurrent agent sessions.

   Success Metrics

   • Zero silent duplicate FRs/ACs after a requirement rename when using Phase 1 tooling (measurable by test: rename a requirement, run specify, verify no duplicate is added).
   • Single-pass /speckit.analyze reliably detects all coverage gaps and conflicts (no need to rerun; deterministic output on unchanged artifacts).
   • Context pack token reduction vs. whole-file dump (qualitative target; specific baseline [NEEDS CLARIFICATION: what is the current typical token count for a whole-file dump?]).
   • Backward compatibility: existing projects without tasks.yaml continue to work without modification.

   Cost of Inaction

   Without this, spec quality degrades silently whenever requirements are reworded — a routine event in UI/product development. Agents build against stale or contradictory requirements; the output of /speckit.analyze becomes unreliable; developers lose trust in the SDD pipeline and fall back to manual spec hygiene, which is the exact workflow Spec Kit is meant to replace.

   Open Questions

   • [NEEDS CLARIFICATION: What is the right granularity for the live inventory — per-feature only, or cross-feature?]
   • [NEEDS CLARIFICATION: How is tasks.yaml kept in sync with tasks.md when a human edits tasks.md directly (the most common path today)?]
   • [NEEDS CLARIFICATION: What commands are in scope for Phase 1 changes — specify and analyze only, or all SDD commands?]
   • [NEEDS CLARIFICATION: Is there a preferred token budget target for the context pack?]

   Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4164 · 471.8 AIC · ⌖ 28.7 AIC · ⊞ 38.1K · ◷
6. github-actions commented on Aug 19, 2026

   

   github-actionsbot

   on Aug 19, 2026 – with GitHub Actions

   Contributor

   More actions

   Feature assessment — structured-ids-context-packs · Stage 4/5: Concept

   Concept: Stop grep-based spec alignment, structured IDs + context packs

   • Slug: structured-ids-context-packs
   • Created: 2026-08-19
   • Recommended option: Option B — Persistent ID index + classify-on-write

   Options

   Option A — Lightweight: Shared ID list in tasks.md

   • Sketch: Extend the existing tasks.md format with a machine-readable header block (YAML frontmatter or a dedicated ## Live IDs section) listing all live FR-/AC-/T- IDs. The check-prerequisites script extracts this list and passes it to commands via JSON output. Commands consult the extracted list before adding requirements. No new file format; no new command.
   • Appetite: small (days)
   • Trade-offs: Wins: zero new files, zero format change for humans, backward-compatible. Sacrifices: IDs still embedded in a markdown file; extraction is fragile if humans reformat; the covers: field (linking tasks to FRs) still has no home.
   • Rabbit holes: Markdown frontmatter parsing is finicky across editors. Does not solve the context pack token-waste problem.

   Option B — Persistent ID index + classify-on-write (recommended)

   • Sketch: Alongside tasks.md, a Python script writes and reads tasks.json — a machine-readable record of all live T-IDs with their status, associated story IDs, and covers links to FR-/AC- IDs. The check-prerequisites script is extended to emit the live ID inventory. A new specify context --task T014 command returns a focused JSON pack: the task record, the FRs/ACs it covers, and matching plan bullets. Before any command adds a requirement, it calls the inventory query to classify the new requirement as duplicate/paraphrase/conflict/new. tasks.md remains the primary human-readable artifact; tasks.json is a derived index rebuilt when tasks.md changes (regenerate-on-read).
   • Appetite: medium (weeks)
   • Trade-offs: Wins: eliminates the grep-based missed-line failure; context pack directly addresses token waste; consistent with existing Python script infrastructure. Sacrifices: adds a new derived file (tasks.json) and a generation step; agents must be updated to call the inventory before writing; introduces a sync dependency between tasks.md and tasks.json.
   • Rabbit holes: Keeping tasks.json in sync with tasks.md when humans edit directly is the hardest part — the sync story needs explicit design. The classify-on-write logic ("same behavior, new words") is inherently heuristic without embeddings and could produce false positives/negatives.

   Option C — Full structured inventory + local embeddings (Phase 1 + Phase 2 together)

   • Sketch: Option B plus a local per-feature embedding index under specs/<feature>/.index/ for paraphrase-pair recall. The embedding index bridges the "confirm modal" ↔ "charge on Pay" gap that string matching misses. Embeddings are generated locally (no cloud); obsolete lines are excluded.
   • Appetite: large (months)
   • Trade-offs: Wins: near-complete paraphrase detection even for radical rewording. Sacrifices: adds a Python embedding dependency (model download, disk storage, inference latency); significantly more complex; embedding quality depends on model choice.
   • Rabbit holes: Model selection, in-repo .gitignore hygiene for the index, inference latency in agent loops, cross-platform support.

   Recommendation

   Option B — Persistent ID index + classify-on-write — addresses the core failure mode within a medium appetite, consistent with Spec Kit's existing Python script architecture. Phase 2 embeddings (Option C) should remain opt-in and are appropriately deferred until Phase 1 proves out the inventory approach.

   The key design decision that must be resolved before specification: how tasks.json is kept in sync with tasks.md when a human edits tasks.md directly. Recommend a regenerate-on-read strategy (tasks.json is rebuilt from tasks.md whenever check-prerequisites runs) to eliminate the sync gap without requiring humans to use a script as the only editor.

   Out of Scope (for the recommended option)

   • Local embedding index / paraphrase recall (Phase 2, Option C)
   • Cross-feature or global ID namespacing
   • Changes to spec.md or plan.md formats
   • Real-time or concurrent-session conflict resolution
   • Hosted or cloud-based vector stores

   Assumptions to Validate

   • The regenerate-on-read approach (rebuild tasks.json from tasks.md on each command invocation) is fast enough to not add noticeable latency to the agent loop.
   • The classify-on-write heuristic (string/ID matching without embeddings) is sufficient to catch the majority of duplicate/paraphrase cases in practice.
   • Adding a covers: field to the tasks.md task format is acceptable to existing Spec Kit users and backward-compatible with projects that omit it.
   • The new specify context command can be delivered as an additional Spec Kit skill/command without requiring a CLI version bump.

   Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4164 · 471.8 AIC · ⌖ 28.7 AIC · ⊞ 38.1K · ◷
7. github-actions commented on Aug 19, 2026

   

   github-actionsbot

   on Aug 19, 2026 – with GitHub Actions

   Contributor

   More actions

   Feature assessment — structured-ids-context-packs · Stage 5/5: Decision — verdict needs-clarification

   Decision: Stop grep-based spec alignment, structured IDs + context packs

   • Slug: structured-ids-context-packs
   • Decided: 2026-08-19
   • Verdict: needs-clarification
   • Artifacts reviewed: intake.md | research.md | problem.md | concept.md

   Scorecard

   Criterion	Rating	Justification
   Problem validity	strong	The failure mode (grep-based context loading misses renamed requirements, producing silent duplicates/contradictions) is real, specific, and directly demonstrated. It undermines a core SDD pipeline promise.
   Evidence strength	weak	One user report with a clear description, but no usage data, no support ticket volume, no community upvotes or corroborating reports. Codebase analysis confirms the architectural gap is real, but demand signal is single-source.
   Value vs. inaction	adequate	Spec drift and unreliable analyze passes erode trust in the SDD pipeline. The cost of inaction compounds as more users iterate on UI features. Impact quantification is absent.
   Feasibility / appetite	adequate	Option B is medium appetite, architecturally consistent with existing Python scripts, and does not require new external dependencies. Key unknowns (sync strategy, command scope) are resolvable during specification.
   Strategic fit	adequate	Structured IDs and context packs align with Spec Kit's goal of reliable, deterministic SDD. The proposal extends existing patterns (FR-IDs, T-IDs, Python scripts) rather than replacing them.
   Risk posture	adequate	Main risks (tasks.md/tasks.json sync drift, classify-on-write false positives) are identified and the recommended regenerate-on-read mitigation is credible. Phase 2 risk is deferred by making it opt-in.

   Verdict & Rationale

   needs-clarification — The problem is real and the concept is credible, but the evidence strength is weak (single user report; no usage data, support ticket volume, or broader demand signal). Per the pipeline's downgrade rule, weak evidence strength blocks a go verdict regardless of other scores.

   Additionally, several design decisions that /speckit.specify would need to act on remain unresolved: the tasks.md ↔ tasks.json sync strategy (regenerate-on-read is assumed but not validated), the scope of command changes for Phase 1, and the API shape of the specify context command. These are resolvable questions, not blockers in principle — but they should be answered before specification can produce a reliable spec.

   This is a promising, internally-consistent idea that deserves a go once the evidence base is strengthened and the open design questions are answered.

   If needs-clarification

   • Blocking questions:
     • [NEEDS CLARIFICATION: Is there broader demand signal beyond this single report? Are there other issues, discussions, or community requests corroborating this failure mode?]
     • [NEEDS CLARIFICATION: What is the exact sync strategy for tasks.json when a human edits tasks.md directly — regenerate-on-read (every command invocation), on-commit hook, or manual?]
     • [NEEDS CLARIFICATION: Which SDD commands are in scope for Phase 1 ID inventory integration — specify and analyze only, or also implement, converge, tasks?]
     • [NEEDS CLARIFICATION: What is the API shape of the specify context command — new CLI subcommand, new agent skill, or both?]
     • [NEEDS CLARIFICATION: Is covers: intended as a new required field in tasks.md task lines, or optional/additive?]
   • Revisit stage: research (to gather broader demand signal); define (to resolve scope and design questions once demand is confirmed)

   Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4164 · 471.8 AIC · ⌖ 28.7 AIC · ⊞ 38.1K · ◷
8. github-actions

   added

   feature-needs-clarificationFeature assessment verdict: needs clarificationFeature assessment verdict: needs clarification

   on Aug 19, 2026
9. Yash-Chindam commented on Aug 19, 2026

   

   Yash-Chindam

   on Aug 19, 2026

   Contributor

   More actions

   I would like to explore a focused contribution for this issue, but the proposed scope is fairly broad. I suggest starting with the smallest Phase 1 slice: a backward-compatible, script-generated requirements/task inventory and a narrow context-pack interface, leaving embeddings and broader command rewrites out of scope.

   Before implementing, could a maintainer confirm the preferred Phase 1 boundary, migration behavior for existing projects without the sidecar, and whether this direction is wanted? If approved, I would be happy to prepare the design and implementation and be assigned to the issue.

   Disclosure: I used ChatGPT to review the repository guidance and draft this comment.
10. mnriem commented on Aug 19, 2026

    

    mnriem

    on Aug 19, 2026

    Collaborator

    More actions

    After a careful review by myself, this doesn't need to go into core as proposed — the whole of Phase 1 can be delivered as an installable, opt-in bundle with zero core changes, which is also the right way to build the adoption signal the assessment flagged as missing.

    Concretely, I'd suggest a paired extension + preset:

    Extension (speckit-inventory) — the read-only primitive:

    • A scripts/ inventory extractor that regenerates every live FR-/NFR-/SC-/T- ID from the existing spec.md/tasks.md on each run and prints JSON. Purely additive, no sidecar, no mutation — so the tasks.yaml↔tasks.md sync problem simply doesn't arise (nothing is a second source of truth).
    • A namespaced speckit.inv.context command that returns a focused context pack (a task plus the requirement IDs it covers) instead of whole-file dumps.
    • Optional before_specify / before_analyze hooks.

    Preset (inventory-alignment) — wires the primitive into the core flow via template overrides (presets sit above extensions in the resolution stack):

    • A wrap override of speckit.specify / speckit.analyze (using the {CORE_TEMPLATE} placeholder) that prepends a "load inventory, then classify each requirement as already-true / edit-existing / conflict / genuinely-new" pre-pass, then falls through to the original command body.
    • An append override of tasks-template adding the optional covers: field.

    Please keep embeddings out (that was the large/opt-in Phase 2). This combination gives essentially all of Phase 1 without a core PR, and if it gets real usage we can revisit promoting the inventory primitive into core.

    One genuine gap worth noting: preset.yml's requires: only declares speckit_version, so there's no formal "requires extension X" dependency to guarantee the extension is installed alongside the preset. That's a small, separable core enhancement I'd track on its own issue rather than block this on.

    We would love to see a PR that will list the community extension and community preset that would support this.

    Disclosure: this comment was prepared with GitHub Copilot (model: Claude Opus 4.8) acting on my behalf.
11. Yash-Chindam

    added a commit that references this issue on Aug 20, 2026

    community: add speckit-inventory extension and inventory-alignment pr…

    ...

    d5030b2