57 lines
4.1 KiB
Markdown
57 lines
4.1 KiB
Markdown
# `.specify/` (Tooling)
|
|
|
|
This folder contains **SpecKit tooling** (templates, scripts, constitution, etc.).
|
|
|
|
## Important
|
|
|
|
- **Do not** create new feature specs in `.specify/spec.md`, `.specify/plan.md`, `.specify/tasks.md`.
|
|
- Active feature specs live under `specs/<NNN>-<slug>/`:
|
|
- `spec.md`
|
|
- `plan.md`
|
|
- `tasks.md`
|
|
- `checklists/requirements.md`
|
|
- Runtime-changing or test-affecting work MUST carry actual test-purpose classification (`Unit`, `Feature`, `Heavy-Governance`, `Browser`), affected lanes, fixture/default cost risks, heavy-family changes, escalation decisions, and minimal validation commands through the active `spec.md`, `plan.md`, and `tasks.md`.
|
|
- Review-oriented checklists MUST surface nativity, shared-family boundaries, state-layer ownership, exception spread, proof depth, and close-out targeting before merge.
|
|
- `.specify/` is the operational workflow. `docs/ui/operator-ux-surface-standards.md` remains a rule/reference document, not a second checklist or review process.
|
|
|
|
## Author Entry Point
|
|
|
|
Use the active feature's `spec.md`, `plan.md`, and `tasks.md` in that order.
|
|
|
|
1. Fill the spec's UI / Surface Guardrail Impact section once. If there is no operator-facing surface change, write a concise `N/A` and do not invent extra prose downstream.
|
|
2. Turn that classification into plan-level handling modes, repository-signal treatment, required proof depth, and the named active feature PR close-out entry.
|
|
3. Carry the same terms into tasks so implementation, review, definition-of-done, exception documentation, and smoke coverage all point at the same guardrail decision.
|
|
|
|
## Review Entry Point
|
|
|
|
Use the active feature's `spec.md`, `plan.md`, and `tasks.md` together with the generated checklist based on `.specify/templates/checklist-template.md`.
|
|
|
|
1. Confirm the spec names the guardrail impact once: native/custom classification, shared-family relevance, state-layer ownership, exception need, and any low-impact `N/A` path.
|
|
2. Confirm the plan turns that into handling modes, repository-signal treatment, required test or smoke depth, and the named active feature PR close-out entry.
|
|
3. Apply the checklist and end with both one review outcome class (`blocker`, `strong-warning`, `documentation-required-exception`, or `acceptable-special-case`) and one workflow outcome (`keep`, `split`, `document-in-feature`, `follow-up-spec`, or `reject-or-split`).
|
|
4. If a guarded surface or exception remains in scope, ensure the active feature PR close-out entry records the final note rather than leaving the decision in scattered review comments.
|
|
|
|
## Low-Impact Rule
|
|
|
|
- Docs-only or template-only work may answer `N/A` or `none`.
|
|
- Do not force fake surface, lane, or exception prose when no operator-facing change or runtime impact exists.
|
|
- Use the low-impact path to stay fast, not to hide a real guarded surface change.
|
|
|
|
## Escalation Rule
|
|
|
|
- Use `blocker` when fake-native drift, hidden host drift, unresolved state ownership, or missing exception boundaries remain.
|
|
- Use `strong-warning` when the change can proceed only after the active workflow records the guardrail risk explicitly.
|
|
- Use `documentation-required-exception` when default rules are intentionally relaxed and the bounded exception record is the remaining requirement.
|
|
- Use `acceptable-special-case` only when the change already fits the declared guardrail contract.
|
|
- Use `document-in-feature` for contained cost or drift that belongs in the active feature.
|
|
- Use `follow-up-spec` only for recurring pain or structural lane or family changes.
|
|
- Use `reject-or-split` when hidden test cost or wrong-lane scope is still unresolved.
|
|
|
|
## Close-Out Rule
|
|
|
|
- The named close-out target for guarded work is the active feature PR close-out entry `Guardrail / Exception / Smoke Coverage`.
|
|
- That entry records the low-impact or representative scenario used, the outcome class, handling mode, workflow outcome, required tests or manual smoke, any exception boundary, duplicate-prompt notes, and any deferred automation.
|
|
- If the change is genuinely low-impact, record a concise `N/A` note rather than fabricating guardrail spread.
|
|
|
|
The files `.specify/spec.md`, `.specify/plan.md`, `.specify/tasks.md` may exist as legacy references only.
|