[Feature]: Move assessment artifacts to a configurable docs/speckit/assessments root through staged migration

Aperta
  • Qualcosa non va?
#5,039 1 commento 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
20/100
Tipo di issue
Funzionalità
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
python
Ambito
tooling

Direzione di ricerca

Start with extensions/assess/README.md, which the issue identifies as documenting current artifact names, slug reuse, refinement, handoff, and path safety. Trace how intake, research, define, shape, and decide select roots and handle prerequisites, then map those paths to the acceptance criteria. Done means staged opt-in, migration, compatibility, and removal behavior are covered across the workflow without breaking the listed contracts.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

triage-out-of-scope

Problem and rationale

The bundled assess extension stores authored idea-assessment artifacts under .specify/assessments/<slug>/, mixing discovery evidence and decisions with tooling/configuration.

Align with github/spec-kit#5037 (https://github.com/github/spec-kit/issues/5037): .specify/ holds tooling/configuration and docs/speckit/ provides a consistent authored-artifact hierarchy. Assessments remain a distinct discovery workflow, separate from SDD delivery and bug assessments. Parallel bug tracking: github/spec-kit#5038 (https://github.com/github/spec-kit/issues/5038).

Proposed solution

Introduce explicit opt-in to a configurable assessment artifact root, defaulting in the new layout to:

docs/speckit/assessments/<slug>/
  intake.md
  research.md
  problem.md
  concept.md
  decision.md

The assessment extension owns selection and migration. Support an environment root override, provisionally SPECIFY_ASSESSMENTS_DIR, subject to existing conventions. Define project-level layout selection and environment/project/default precedence so absent environment overrides do not accidentally redirect later stages. Do not automatically persist transient overrides. Relative paths resolve against the Spec Kit project root.

Apply one resolved root consistently across intake/research/define/shape/decide, prerequisites, slug uniqueness/context reuse, artifact references/refinement, and decision-to-SDD handoff. Preserve recorded paths and ongoing workflow selection rather than silently rebasing them under changed configuration.

Migration is explicit and preserves content. Competing assessment copies cause a conflict, not arbitrary precedence, automatic merging, or overwrites. Preserve discovery stage prerequisites, evidence/verdict requirements, empty-project support, and optional forward handoff to SDD. Relocation must not introduce automatic SDD execution or couple discovery to SDD layout selection.

Four-stage rollout

  1. Opt-in: Add unified/custom roots while retaining .specify/assessments/ defaults for non-opted-in projects.
  2. Deprecation warnings: Warn on the legacy root with actionable migration guidance; no file moves or behavior changes.
  3. Default flip with legacy opt-out: Default new adoption to docs/speckit/assessments/; preserve explicit compatibility for existing projects and in-progress assessments.
  4. Removal: Retire legacy-root support after an adequate announced transition period. Unmigrated assessments receive migration errors instead of missing-prerequisite errors or duplicate artifacts.

Do not assign specific release versions. PR boundaries alone are not compatibility windows; allow release/adoption time. Assessment, bug, and core rollouts may progress independently.

Acceptance criteria

  • Initial opt-in preserves legacy defaults unless explicitly selected.
  • Opted-in defaults use docs/speckit/assessments/<slug>/; an environment override relocates the root.
  • Layout selection, persistence, precedence, existing-project detection, and project-relative resolution are explicit across all five commands.
  • Invalid configuration produces actionable errors rather than silent fallback.
  • All artifact reads/writes, prerequisites, slug collision checks, context reuse, refinement, and handoff references use the selected root.
  • Existing assessments, recorded paths, and ongoing stage selection remain coherent across upgrades/configuration changes.
  • Migration is explicit and preserves content; conflicts across roots are reported without silent precedence or overwrites.
  • Source-code write restrictions, overwrite protection, and path-safety guarantees remain intact, including symlink-component rejection and project containment for custom roots.
  • Stage prerequisites, evidence/verdict rules, empty-project support, and deliberate optional SDD handoff remain unchanged.
  • Warnings do not change behavior; default flip retains documented legacy opt-out; removal reports clear migration errors.
  • Positive and negative coverage demonstrates legacy compatibility, opt-in/custom roots, absent overrides, invalid/unsafe roots, conflicts, and pipeline continuity.
  • Extension instructions, documentation, examples, handoff guidance, and directly related references are updated together.
  • Stages provide adequate announced adoption time without committing to specific versions.

Alternatives and scope

Keeping .specify/assessments/ avoids migration but not separation of authored artifacts from tooling. Putting discovery inside the SDD root blurs discovery/delivery. Core-owned extension paths or a mandatory shared parent variable unnecessarily couple independently configurable workflows. Environment-only selection and automatic moves risk broken continuity and duplicates.

This is a separate staged tracking issue, not an all-stages PR or a requirement to share implementation/release schedules with core and bug work.

extensions/assess/README.md documents current artifact names, slug reuse, explicit artifact refinement, optional decision.md handoff, and symlink rejection/project containment. Relocation must preserve those contracts. All agents are affected.

Replaces the mistakenly filed fork issue https://github.com/mnriem/spec-kit/issues/60, with the user's authorization.

AI disclosure

Drafted and filed on behalf of @mnriem using GitHub Copilot App, powered by GPT-6.1 Sol (gpt-6.1-sol), in human-supervised interactive mode. The agent inspected the bundled README and drafted the rationale, rollout, and acceptance criteria from the user-approved discussion. The user authorized upstream filing. Reasoning-effort setting was not available to report. No implementation changes were made.

Lingua principale
Python
Stelle
149k
Fork
13.4k
Merge medio
1g 5h
PR unite (30g)
223

Preparare l'ambiente

Apri in Codespaces

Avvia il container di sviluppo del progetto nel browser, con il tuo account GitHub.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di github/spec-kit

Tutte le issue di github/spec-kit

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.