diff --git a/skills/sparv/SKILL.md b/skills/sparv/SKILL.md index 81719e9..7c7c9cb 100644 --- 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: | ASSUMPTION: ` +- 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 --desc "..." +``` + ## External Memory (Two Files) Initialize (run in project root): diff --git a/skills/sparv/references/methodology.md b/skills/sparv/references/methodology.md index 4654bab..cc6b773 100644 --- 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: | ASSUMPTION: ` +- 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 --desc "..." +``` + ## Specify (10-Point Scale) Each item scores 0/1/2, total 0-10; `>=9` required to enter Plan: diff --git a/skills/sparv/scripts/changelog-update.sh b/skills/sparv/scripts/changelog-update.sh new file mode 100755 index 0000000..253545c --- /dev/null +++ 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 --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" diff --git a/skills/sparv/scripts/init-session.sh b/skills/sparv/scripts/init-session.sh index 39eaf07..9c0a761 100755 --- 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 + + + +## Decisions + + + + +## Gotchas + + + + +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