mirror of
https://github.com/cexll/myclaude.git
synced 2026-02-14 03:31:58 +08:00
e122d8ff25
- Add Uncertainty Declaration (G3): declare assumptions when score < 2 - Add Requirement Routing: Quick/Full mode based on scope - Add Context Acquisition: optional kb.md check before Specify - Add Knowledge Base: .sparv/kb.md for cross-session patterns - Add changelog-update.sh: maintain CHANGELOG by type Generated with SWE-Agent.ai Co-Authored-By: SWE-Agent.ai <noreply@swe-agent.ai>
133 lines
3.6 KiB
Markdown
133 lines
3.6 KiB
Markdown
# SPARV Methodology (Short)
|
|
|
|
This document is a quick reference; the canonical spec is in `SKILL.md`.
|
|
|
|
## Five Phases
|
|
|
|
- **Specify**: Write requirements as verifiable specs (10-point gate)
|
|
- **Plan**: Break into atomic tasks (2-5 minute granularity)
|
|
- **Act**: TDD-driven implementation; write to journal every 2 actions
|
|
- **Review**: Spec conformance → Code quality; maximum 3 fix rounds
|
|
- **Vault**: Archive session (state + journal)
|
|
|
|
## Enhanced Rules (v1.1)
|
|
|
|
### Uncertainty Declaration (G3)
|
|
|
|
When any Specify dimension scores < 2:
|
|
- Declare: `UNCERTAIN: <what> | ASSUMPTION: <fallback>`
|
|
- List all assumptions in journal before Plan
|
|
- Offer 2-3 options for ambiguous requirements
|
|
|
|
### Requirement Routing
|
|
|
|
| Mode | Condition | Flow |
|
|
|------|-----------|------|
|
|
| **Quick** | score >= 9 AND <= 3 files AND no EHRB | Specify → Act → Review |
|
|
| **Full** | otherwise | Specify → Plan → Act → Review → Vault |
|
|
|
|
### Context Acquisition (Optional)
|
|
|
|
Before Specify scoring:
|
|
1. Check `.sparv/kb.md` for existing patterns/decisions
|
|
2. If insufficient, scan codebase for relevant files
|
|
3. Document findings in journal under `## Context`
|
|
|
|
### Knowledge Base Maintenance
|
|
|
|
During Vault phase, update `.sparv/kb.md`:
|
|
- **Patterns**: Reusable code patterns discovered
|
|
- **Decisions**: Architectural choices + rationale
|
|
- **Gotchas**: Common pitfalls + solutions
|
|
|
|
### CHANGELOG Update
|
|
|
|
```bash
|
|
~/.claude/skills/sparv/scripts/changelog-update.sh --type <Added|Changed|Fixed|Removed> --desc "..."
|
|
```
|
|
|
|
## Specify (10-Point Scale)
|
|
|
|
Each item scores 0/1/2, total 0-10; `>=9` required to enter Plan:
|
|
|
|
1) Value: Why do it, are benefits/metrics verifiable
|
|
2) Scope: MVP + what's out of scope
|
|
3) Acceptance: Testable acceptance criteria
|
|
4) Boundaries: Error/performance/compatibility/security critical boundaries
|
|
5) Risk: EHRB/dependencies/unknowns + handling approach
|
|
|
|
If below threshold, keep asking—don't "just start coding."
|
|
|
|
## Journal Convention (Unified Log)
|
|
|
|
All Plan/Progress/Findings go into `.sparv/journal.md`.
|
|
|
|
Recommended format (just append, no need to "insert into specific sections"):
|
|
|
|
```markdown
|
|
## 14:32 - Action #12
|
|
- Tool: Edit
|
|
- Result: Updated auth flow
|
|
- Next: Add test for invalid token
|
|
```
|
|
|
|
## 2-Action Save
|
|
|
|
Hook triggers `save-progress.sh` after each tool call; script only writes to journal when `action_count` is even.
|
|
|
|
## 3-Failure Protocol
|
|
|
|
When you fail consecutively, escalate by level:
|
|
|
|
1. Diagnose and fix (read errors, verify assumptions, minimal fix)
|
|
2. Alternative approach (change strategy/entry point)
|
|
3. Escalate (stop: document blocker + attempted solutions + request user decision)
|
|
|
|
Tools:
|
|
|
|
```bash
|
|
~/.claude/skills/sparv/scripts/failure-tracker.sh fail --note "short reason"
|
|
~/.claude/skills/sparv/scripts/failure-tracker.sh reset
|
|
```
|
|
|
|
## 3-Question Reboot Test
|
|
|
|
Self-check before session ends (or when lost):
|
|
|
|
1) Where am I? (current_phase)
|
|
2) Where am I going? (next_phase)
|
|
3) How do I prove completion? (completion_promise + evidence at journal end)
|
|
|
|
```bash
|
|
~/.claude/skills/sparv/scripts/reboot-test.sh --strict
|
|
```
|
|
|
|
## EHRB (High-Risk Changes)
|
|
|
|
Detection items (any match requires explicit user confirmation):
|
|
|
|
- Production access
|
|
- Sensitive data
|
|
- Destructive operations
|
|
- Billing external API
|
|
- Security-critical changes
|
|
|
|
```bash
|
|
~/.claude/skills/sparv/scripts/check-ehrb.sh --diff --fail-on-flags
|
|
```
|
|
|
|
## state.yaml (Minimal Schema)
|
|
|
|
Scripts only enforce 4 core fields; other fields are optional:
|
|
|
|
```yaml
|
|
session_id: "20260114-143022"
|
|
current_phase: "act"
|
|
action_count: 14
|
|
consecutive_failures: 0
|
|
max_iterations: 12
|
|
iteration_count: 0
|
|
completion_promise: "All acceptance criteria have tests and are green."
|
|
ehrb_flags: []
|
|
```
|