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

Ouverte
  • Quelque chose ne va pas ?
#5,039 1 commentaire 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

Personne n'a encore pris cette issue.

Évaluation

Difficulté
5/5
Temps estimé
Plus d'une semaine
Accessibilité débutants
20/100
Type d'issue
Fonctionnalité
Clarté
Clairement spécifiée
Activité
Active
Stack technique
python
Domaine
tooling

Piste de recherche

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.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

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.

Langage dominant
Python
Étoiles
149k
Forks
13.4k
Merge moyen
1 j 5 h
PR mergées (30 j)
223

Préparer son environnement

Ouvrir dans Codespaces

Lance le conteneur de développement du projet dans votre navigateur, avec votre propre compte GitHub.

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de github/spec-kit

Toutes les issues de github/spec-kit

Issues similaires

Plus d'issues Python

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.