Govkit Spec Planning

---
name: govkit-spec-planning
description: Generate a feature plan (plan.md) and eval_criteria.yaml from NFRs and acceptance scenarios. Use when the user asks to plan a feature or invokes /govkit-spec-planning.
---

Plan the implementation of the named feature. When invoked, determine the feature name from the user's request; if it is not provided, ask before proceeding.

## Behavior contract (skip unless this project has one)

Read `authority` in `.govkit/skill_context.yaml` before anything else. If
`source` is `none` — the default, and where most projects are — **skip this
section entirely**: nothing in it applies, and you should not mention it.

If `source` is `pdg`, this feature's behavior is a **versioned commitment**.
An approved baseline binds its Rules and scenarios to an exact revision, and
what somebody approved is that revision — not the working tree in front of
you, and not your reading of it. The governing rule is the one govkit
installed as `behavior-contract`; it is already loaded, and it is binding.

Before relying on anything in the feature folder:

- Run the `validate-baseline` and `verify-authority` checks exactly as that
  rule specifies them. Both need `--target` and `--baseline`, and
  `verify-authority` also needs `--commitment` — omit it and the answer is
  *not authorized* about the pointer you did not supply, which says nothing
  about your work.
- **Check `sources` in the baseline first.** More than one entry means the
  contract spans repositories and every one of them needs its own
  `--source <source_key>=<path>` checkout. Without them you get refusals
  about missing sources, which are not a verdict on the contract.
- **Drift means stop.** The spec in front of you is not the one that was
  approved, and everything you plan from it inherits that.
- **Unverified is not permission.** An unreachable graph, or an unset
  `GOVKIT_PDG_URL`, leaves the question unanswered rather than answered yes.

Then change nothing that is committed. A scope change, an exclusion you
inferred, a behavior nobody asked for, or a relaxed threshold is a decision
for a person: name the scenario in conflict and wait. You may still refactor,
and this plan may still evolve, as long as every committed scenario keeps
passing.

## Multi-service repos

Read `.govkit/skill_context.yaml` before planning. When it lists more than
one entry under `architecture.services`, this repo holds several services
and every path in your output has to land inside one of them:

```yaml
architecture:
  source_root: ''
  services:
    - name: billing
      root: src/billing
    - name: orders
      root: src/orders
```

1. Work out which service the feature belongs to. Take it from the request
   when it names one — by service name, or by a path under that service's
   `root`.
2. If the request names none, **ask which service to plan for** and list the
   names. Do not guess, and do not plan across all of them at once.
3. Prefix every file path in your output with that service's `root`. A task
   touching `services/pricing.py` in the `orders` service is
   `src/orders/services/pricing.py`.
4. Name the chosen service in the plan summary, so a reader knows which part
   of the repo the plan applies to.

When `architecture.services` is absent, the repo holds a single service.
Use `architecture.source_root` as the prefix instead — an empty value means
the layer folders sit at the repo root and paths need no prefix.

## Inputs to read

Feature specs:
- NFRs: `features/<feature_name>/nfrs.md`
- Acceptance: `features/<feature_name>/acceptance.feature`

Architecture standards:
- `docs/{{docs_area}}/architecture/**`

Evaluation standards:
- Global evaluation contract: `docs/{{docs_area}}/evaluation/eval_criteria.md`

Existing artifacts (read if present, update if needed):
- Feature eval config: `features/<feature_name>/eval_criteria.yaml`

## Instructions

1. Read all inputs listed above.
2. Summarize the business goal and scope of the feature.
2a. Populate the plan's `### Out of scope` from `nfrs.md` `## Out of scope`:
   - If `nfrs.md` has a non-empty `## Out of scope` section, copy its entries into the plan verbatim (author-declared — no marker).
   - If `## Out of scope` is missing or empty, infer the deferred capabilities from the spec's negative space (domain neighbors with no scenarios), then BOTH:
     - insert `<!-- INFERRED: not declared in nfrs.md ## Out of scope; confirm with feature owner -->` directly under the plan's `### Out of scope` heading, and
     - state in the planning summary that Out-of-scope was inferred and should be confirmed.
3. Identify required design elements per **this project's architecture**:
   - Read `.govkit/skill_context.yaml` for the architecture style and the
     folder hints under `architecture.layers` (inbound / outbound / domain).
   - Read `docs/{{docs_area}}/architecture/BOUNDARIES.md` for the canonical layer
     contract and `LAYER_IMPLEMENTATION.md` for the layer-by-layer guidance.
   - List the inbound entry points, domain logic modules, outbound
     dependencies, and any infrastructure adapters the feature needs —
     using the project's own folder names, not generic ones.
4. Flag any deviation from architecture contracts:
<!-- govkit:docs-area backend -->
   - `ARCH_CONTRACT.md`
   - `BOUNDARIES.md`
   - `API_CONVENTIONS.md`
   - `SECURITY_AUTH_PATTERNS.md`
<!-- /govkit:docs-area -->
<!-- govkit:docs-area data -->
   - `ARCH_CONTRACT.md`, `BOUNDARIES.md`, `DATA_QUALITY_CONTRACT.md`,
     `PII_HANDLING_CONTRACT.md`, `LINEAGE_CONTRACT.md`, `ENVIRONMENTS.md`
   - Query conventions from the selected stack overlay, when installed
<!-- /govkit:docs-area -->
5. Determine ADR need. Mark **ADR required** if any of these occur:
   - New outbound dependency or external integration
   - Boundary change or exception
   - New pattern or approach not already documented
6. Produce two outputs:

### Output A: Plan (Markdown)
Create `features/<feature_name>/plan.md` content with:
- Task checklist (files/modules to create or edit)
- Test plan (unit, integration, contract)
- LLM eval hooks and where they run
- Risks, open questions, and follow-ups
- ADR status (required or not required)

### Output B: Feature Eval Criteria (YAML)
Create or update `features/<feature_name>/eval_criteria.yaml` to conform to:
- `docs/{{docs_area}}/evaluation/eval_criteria.md` schema and thresholds
Include, at minimum:
- FIRST enforcement settings
- 7 virtues enforcement settings
- Any LLM-specific dimensions required by this feature (groundedness, safety, tone, etc.)
- Dataset or prompt-set reference placeholder if none exists yet
- Fail-on-regression behavior

### Output A: Evaluation Compliance Summary

plan.md must include an Evaluation Compliance Summary with predicted FIRST and Virtue scores. Use the scoring rubrics for reference:

- FIRST rubric: `docs/{{docs_area}}/evaluation/FIRST_SCORING_RUBRIC.md`
- Virtue rubric: `docs/{{docs_area}}/evaluation/VIRTUE_SCORING_RUBRIC.md`

Do not proceed if predicted FIRST average or Virtue average is below 4.0.

## Output rules

- Output A first, then Output B.
- Keep Output B as valid YAML and ready to commit.
- No implementation code in this step.

This output will feed `/govkit-implementation-plan`.

<!-- govkit:docs-area data -->
### Data projects

Use these data-specific output contracts:

- NFR categories are `freshness`, `quality`, `pii`, `lineage`, `cost`
  (plus `reliability`, `observability`, `compliance` where relevant).
  Tag scenarios `@nfr-<category>` — the eval gate cross-checks every
  populated category against the tags.
- `eval_criteria.yaml` uses the data schema: `mode: deterministic` (or
  `none`), and each criterion's `measurement` names a query or CI check
  with `threshold` as a predicate string. No LLM evaluator tools.
- Cite the data quality, freshness, and lineage contracts under
  `docs/data/architecture/`.
<!-- /govkit:docs-area -->