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

Đang mở
  • Có gì không ổn?
#5,039 1 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
20/100
Loại issue
Tính năng
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
python
Lĩnh vực
tooling

Hướng nghiên cứu

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.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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.

Ngôn ngữ chính
Python
Star
149k
Fork
13.4k
Merge trung bình
1 ngày 5 giờ
Pull request đã merge (30 ngày)
223

Chuẩn bị môi trường

Mở trong Codespaces

Khởi chạy dev container của dự án ngay trên trình duyệt, bằng tài khoản GitHub của bạn.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của github/spec-kit

Tất cả issue của github/spec-kit

Issue tương tự

Thêm issue về Python

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.