Scope some workflow steps to individual features
This commit is contained in:
parent
53e83a666b
commit
77b25c461e
GPG key ID:
34FDC68B51191A4D
5 changed files with 77 additions and 53 deletions
|
|
@ -1,19 +1,25 @@
|
|||
---
|
||||
description: Create an implementation plan with formal verification strategy
|
||||
argument-hint: <feature-name>
|
||||
allowed-tools: [Read, Write, Edit, Glob, Grep, Task]
|
||||
---
|
||||
|
||||
# FormSpec Plan
|
||||
|
||||
You are creating an implementation plan that bridges the formal TLA+ specification to concrete code, with a verification strategy ensuring each formal property is checked by implementation-level tools.
|
||||
You are creating an implementation plan for a single feature, bridging its formal TLA+ properties to concrete code with a verification strategy ensuring each property is checked by implementation-level tools.
|
||||
|
||||
## Steps
|
||||
|
||||
### 1. Read all artifacts
|
||||
### 1. Read artifacts
|
||||
|
||||
**$ARGUMENTS must provide a feature name.** If empty, ask the user for a feature name. The feature name should be the kebab-case identifier used when the feature was designed (e.g., `user-auth`, `billing`).
|
||||
|
||||
**Locate the feature directory**: Glob for `spec/features/*-<feature-name>/design.md`. If no match is found, tell the user to run `/formspec.design.1 <feature-name>` first and stop. If multiple matches exist (unlikely), use the most recent by date prefix.
|
||||
|
||||
Read:
|
||||
- `spec/system.md`
|
||||
- All feature design docs: Glob for `spec/features/*/design.md`
|
||||
- The feature's `design.md`
|
||||
- Other feature design docs under `spec/features/` (for cross-feature context)
|
||||
- `spec/formal/System.tla`
|
||||
- `spec/formal/System.cfg`
|
||||
- `spec/formal/traceability.md`
|
||||
|
|
@ -22,33 +28,37 @@ All of these must exist. If any are missing, tell the user which prerequisite co
|
|||
|
||||
### 2. Validate formal verification status
|
||||
|
||||
Check `spec/formal/traceability.md`. Every formalizable property must have status `checked` (meaning TLC has verified it). If any property has status `formalized`, `violated`, or `not-yet-formalized` without adequate justification:
|
||||
Check `spec/formal/traceability.md`. Every formalizable property **sourced from this feature's design doc** must have status `checked` (meaning TLC has verified it). If any such property has status `formalized`, `violated`, or `not-yet-formalized` without adequate justification:
|
||||
- Tell the user which properties are not yet verified
|
||||
- Direct them to run `/formspec.formalize.2` first
|
||||
- Stop
|
||||
|
||||
### 3. Generate spec/plan.md
|
||||
### 3. Generate the feature's plan
|
||||
|
||||
Write `spec/plan.md` with these sections:
|
||||
Write `spec/features/YYYY-MM-DD-<feature-name>/plan.md` (in the same directory as the feature's `design.md`) with these sections:
|
||||
|
||||
```markdown
|
||||
# Implementation Plan
|
||||
# Implementation Plan: <Feature Name>
|
||||
|
||||
## Technology Choices
|
||||
|
||||
[Language(s), frameworks, infrastructure. Each choice must be justified against the formal properties where relevant.]
|
||||
[Language(s), frameworks, infrastructure needed for this feature. Each choice must be justified against the formal properties where relevant.]
|
||||
|
||||
Example: "Rust for the auth module — ownership system prevents use-after-free, directly satisfying the MemorySafety invariant. Go for the API gateway — goroutines with race detector verify the NoConcurrentAccess property at test time."
|
||||
|
||||
Do not justify choices that have no relationship to formal properties — just state them.
|
||||
|
||||
For the first feature in a project, this section establishes the system-wide technology stack. For subsequent features, reference existing choices and only document additions or deviations.
|
||||
|
||||
## Architecture
|
||||
|
||||
[Component structure, communication patterns, data flow. Reference how the architecture maps to the TLA+ model's actors and processes. Where design docs define Interface Contracts, the architecture should describe how components connect through those interfaces and confirm that the planned component boundaries align with the contracts.]
|
||||
[Component structure, communication patterns, data flow for this feature. Reference how the architecture maps to the TLA+ model's actors and processes. Where design docs define Interface Contracts, the architecture should describe how components connect through those interfaces and confirm that the planned component boundaries align with the contracts.]
|
||||
|
||||
For subsequent features, describe how this feature's components integrate with the existing system — what it reuses, what it adds, and where boundaries lie.
|
||||
|
||||
## Verification Strategy
|
||||
|
||||
[A table mapping each TLA+ property to implementation-level verification methods.]
|
||||
[A table mapping each of this feature's TLA+ properties to implementation-level verification methods. Include system-level properties (e.g., architectural constraints) that this feature's implementation must satisfy.]
|
||||
|
||||
| Source Document | Requirement ID | TLA+ Property | Verification Method | Tool |
|
||||
|----------------|----------------|---------------|---------------------|------|
|
||||
|
|
@ -64,7 +74,7 @@ Verification methods include:
|
|||
- **Formal proofs**: F* modules that verify TLA+ properties
|
||||
- **Test coverage**: Specific test cases derived from TLC state exploration
|
||||
|
||||
Every TLA+ property in the traceability matrix must have at least one verification method. Properties with only "manual review" are not acceptable — find a tool-assisted method.
|
||||
Every TLA+ property in the traceability matrix that is sourced from this feature must have at least one verification method. Properties with only "manual review" are not acceptable — find a tool-assisted method.
|
||||
|
||||
When a TLA+ property is satisfied structurally, do not claim it is verified by a runtime test. A no-op test function that "checks" a structurally-guaranteed property is misleading — it will never fail, so it provides no signal. Instead, record the verification method as "Structural guarantee" and explain what data model decision enforces it.
|
||||
|
||||
|
|
@ -78,7 +88,7 @@ When a TLA+ property is satisfied structurally, do not claim it is verified by a
|
|||
|
||||
## Testing Strategy
|
||||
|
||||
[Unit, integration, and property-based testing approach.]
|
||||
[Unit, integration, and property-based testing approach for this feature.]
|
||||
|
||||
- How tests trace back to TLA+ properties
|
||||
- Property-based test generators derived from the TLA+ state space
|
||||
|
|
@ -89,11 +99,11 @@ When a TLA+ property is satisfied structurally, do not claim it is verified by a
|
|||
### 4. Quality check
|
||||
|
||||
Before finishing, verify:
|
||||
- Every TLA+ property from traceability.md appears in the Verification Strategy
|
||||
- Every feature's user stories are addressed by the architecture
|
||||
- Every TLA+ property sourced from this feature in traceability.md appears in the Verification Strategy
|
||||
- Every user story from this feature's design doc is addressed by the architecture
|
||||
- Technology choices don't contradict architectural constraints from system.md
|
||||
- The verification strategy is actually executable (tools exist, are available, and can check what's claimed)
|
||||
|
||||
### 5. Report
|
||||
|
||||
Summarize the plan and suggest proceeding with `/formspec.tasks.5` to break it into implementable tasks.
|
||||
Summarize the plan and suggest proceeding with `/formspec.tasks.5 <feature-name>` to break it into implementable tasks.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue