feat: add sparv enhanced rules v1.1

- 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>
2026-02-05 02:30:26 +08:00 · 2026-01-17 13:12:10 +08:00
parent 6985a30a6a
commit e122d8ff25
4 changed files with 228 additions and 0 deletions
--- a/skills/sparv/SKILL.md
+++ b/skills/sparv/SKILL.md
@@ -17,6 +17,56 @@ Goal: Complete "requirements → verifiable delivery" in one pass, recording key
 - **EHRB**: Require explicit user confirmation when high-risk detected (production/sensitive data/destructive/billing API/security-critical).
 - **Fixed Phase Names**: `specify|plan|act|review|vault` (stored in `.sparv/state.yaml:current_phase`).

+## 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
+
+Example:
+```
+UNCERTAIN: deployment target | ASSUMPTION: Docker container
+UNCERTAIN: auth method | OPTIONS: JWT / OAuth2 / Session
+```
+
+### Requirement Routing
+
+| Mode | Condition | Flow |
+|------|-----------|------|
+| **Quick** | score >= 9 AND <= 3 files AND no EHRB | Specify → Act → Review |
+| **Full** | otherwise | Specify → Plan → Act → Review → Vault |
+
+Quick mode skips formal Plan phase but still requires:
+- Completion promise written to journal
+- 2-action save rule applies
+- Review phase mandatory
+
+### 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`
+
+Skip if user explicitly provides full 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
+
+Use during Review or Vault phase for non-trivial changes:
+```bash
+~/.claude/skills/sparv/scripts/changelog-update.sh --type <Added|Changed|Fixed|Removed> --desc "..."
+```
+
 ## External Memory (Two Files)

 Initialize (run in project root):
--- a/skills/sparv/references/methodology.md
+++ b/skills/sparv/references/methodology.md
@@ -10,6 +10,42 @@ This document is a quick reference; the canonical spec is in `SKILL.md`.
 - **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:
--- a/skills/sparv/scripts/changelog-update.sh
+++ b/skills/sparv/scripts/changelog-update.sh
@@ -0,0 +1,112 @@
+#!/bin/bash
+# SPARV Changelog Update Script
+# Adds entries to .sparv/CHANGELOG.md under [Unreleased] section
+
+set -e
+
+usage() {
+	cat <<'EOF'
+Usage: changelog-update.sh --type <TYPE> --desc "description" [--file PATH]
+
+Adds a changelog entry under [Unreleased] section.
+
+Options:
+  --type TYPE   Change type: Added|Changed|Fixed|Removed
+  --desc DESC   Description of the change
+  --file PATH   Custom changelog path (default: .sparv/CHANGELOG.md)
+
+Examples:
+  changelog-update.sh --type Added --desc "User authentication module"
+  changelog-update.sh --type Fixed --desc "Login timeout issue"
+EOF
+}
+
+CHANGELOG=".sparv/CHANGELOG.md"
+TYPE=""
+DESC=""
+
+while [ $# -gt 0 ]; do
+	case "$1" in
+	-h|--help) usage; exit 0 ;;
+	--type) TYPE="$2"; shift 2 ;;
+	--desc) DESC="$2"; shift 2 ;;
+	--file) CHANGELOG="$2"; shift 2 ;;
+	*) usage >&2; exit 1 ;;
+	esac
+done
+
+# Validate inputs
+if [ -z "$TYPE" ] || [ -z "$DESC" ]; then
+	echo "❌ Error: --type and --desc are required" >&2
+	usage >&2
+	exit 1
+fi
+
+# Validate type
+case "$TYPE" in
+Added|Changed|Fixed|Removed) ;;
+*)
+	echo "❌ Error: Invalid type '$TYPE'. Must be: Added|Changed|Fixed|Removed" >&2
+	exit 1
+	;;
+esac
+
+# Check changelog exists
+if [ ! -f "$CHANGELOG" ]; then
+	echo "❌ Error: Changelog not found: $CHANGELOG" >&2
+	echo "   Run init-session.sh first to create it." >&2
+	exit 1
+fi
+
+# Check if [Unreleased] section exists
+if ! grep -q "## \[Unreleased\]" "$CHANGELOG"; then
+	echo "❌ Error: [Unreleased] section not found in $CHANGELOG" >&2
+	exit 1
+fi
+
+# Check if the type section already exists under [Unreleased]
+# We need to insert after [Unreleased] but before the next ## section
+TEMP_FILE=$(mktemp)
+trap "rm -f $TEMP_FILE" EXIT
+
+# Find if ### $TYPE exists between [Unreleased] and next ## section
+IN_UNRELEASED=0
+TYPE_FOUND=0
+TYPE_LINE=0
+UNRELEASED_LINE=0
+NEXT_SECTION_LINE=0
+
+line_num=0
+while IFS= read -r line; do
+	((line_num++))
+	if [[ "$line" =~ ^##[[:space:]]\[Unreleased\] ]]; then
+		IN_UNRELEASED=1
+		UNRELEASED_LINE=$line_num
+	elif [[ $IN_UNRELEASED -eq 1 && "$line" =~ ^##[[:space:]] && ! "$line" =~ ^###[[:space:]] ]]; then
+		NEXT_SECTION_LINE=$line_num
+		break
+	elif [[ $IN_UNRELEASED -eq 1 && "$line" =~ ^###[[:space:]]$TYPE ]]; then
+		TYPE_FOUND=1
+		TYPE_LINE=$line_num
+	fi
+done < "$CHANGELOG"
+
+if [ $TYPE_FOUND -eq 1 ]; then
+	# Append under existing ### $TYPE section
+	awk -v type_line="$TYPE_LINE" -v desc="$DESC" '
+		NR == type_line { print; getline; print; print "- " desc; next }
+		{ print }
+	' "$CHANGELOG" > "$TEMP_FILE"
+else
+	# Create new ### $TYPE section after [Unreleased]
+	awk -v unreleased_line="$UNRELEASED_LINE" -v type="$TYPE" -v desc="$DESC" '
+		NR == unreleased_line { print; print ""; print "### " type; print "- " desc; next }
+		{ print }
+	' "$CHANGELOG" > "$TEMP_FILE"
+fi
+
+mv "$TEMP_FILE" "$CHANGELOG"
+
+echo "✅ Added to $CHANGELOG:"
+echo "   ### $TYPE"
+echo "   - $DESC"
--- a/skills/sparv/scripts/init-session.sh
+++ b/skills/sparv/scripts/init-session.sh
@@ -137,6 +137,35 @@ Format based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 EOF
 }

+# Initialize kb.md (knowledge base) if not exists
+init_kb() {
+	local kb_file="$SPARV_ROOT/kb.md"
+	[ -f "$kb_file" ] && return 0
+
+	cat > "$kb_file" << 'EOF'
+# Knowledge Base
+
+Cross-session knowledge accumulated during SPARV workflows.
+
+---
+
+## Patterns
+
+<!-- Reusable code patterns discovered -->
+
+## Decisions
+
+<!-- Architectural choices + rationale -->
+<!-- Format: - [YYYY-MM-DD]: decision | rationale -->
+
+## Gotchas
+
+<!-- Common pitfalls + solutions -->
+<!-- Format: - [issue]: cause | solution -->
+
+EOF
+}
+
 # Check for active session
 active_session="$(find_active_session)"

@@ -162,6 +191,7 @@ mkdir -p "$HISTORY_DIR"
 # Initialize global files
 init_history_index
 init_changelog
+init_kb

 # Create state.yaml
 cat > "$SESSION_DIR/state.yaml" << EOF