docs: add developer profiling, execution hardening, and idempotent mark-complete to docs (#1108)

Update documentation for features added since v1.25.1: - CHANGELOG.md: Add [Unreleased] entries for developer profiling pipeline, execution hardening (pre-wave check, cross-plan contracts, export spot-check), and idempotent requirements mark-complete - README.md: Add /gsd:profile-user command to utilities table - docs/COMMANDS.md: Add full /gsd:profile-user command documentation with flags, generated artifacts, and usage examples - docs/FEATURES.md: Add Feature 33 (Developer Profiling) with 8 behavioral dimensions, pipeline modules, and requirements; add Feature 34 (Execution Hardening) with 3 quality components - docs/AGENTS.md: Add gsd-user-profiler agent documentation and tool permissions entry
2026-03-16 15:39:52 -04:00
parent 460f92e727
commit 80605d2051
5 changed files with 113 additions and 0 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,16 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

 ## [Unreleased]

+### Added
+- **`/gsd:profile-user` command** — Developer behavioral profiling from session analysis across 8 dimensions (communication, decisions, debugging, UX, vendor choices, frustrations, learning style, explanation depth). Generates `USER-PROFILE.md`, `/gsd:dev-preferences`, and `CLAUDE.md` profile section for personalized responses. Includes `--questionnaire` fallback and `--refresh` for re-analysis
+- **Execution hardening** — Three quality improvements to the execution pipeline:
+  - Pre-wave dependency check in `execute-phase`: verifies key-links from prior wave artifacts before spawning next wave
+  - Cross-Plan Data Contracts (Dimension 9) in plan-checker: detects incompatible transformations between plans sharing data pipelines
+  - Export-level spot check in `verify-phase`: catches dead stores that exist in wired files but are never called
+
+### Fixed
+- **Requirements `mark-complete` is now idempotent** — Re-marking already-completed requirements returns `already_complete` instead of `not_found` (#948)
+
 ## [1.25.0] - 2026-03-16

 ### Added
--- a/README.md
+++ b/README.md
@@ -548,6 +548,7 @@ You're never locked in. The system adapts.
 | `/gsd:quick [--full] [--discuss] [--research]` | Execute ad-hoc task with GSD guarantees (`--full` adds plan-checking and verification, `--discuss` gathers context first, `--research` investigates approaches before planning) |
 | `/gsd:health [--repair]` | Validate `.planning/` directory integrity, auto-repair with `--repair` |
 | `/gsd:stats` | Display project statistics — phases, plans, requirements, git metrics |
+| `/gsd:profile-user [--questionnaire] [--refresh]` | Generate developer behavioral profile from session analysis for personalized responses |

 <sup>¹ Contributed by reddit user OracleGreyBeard</sup>

--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -329,6 +329,29 @@ GSD uses a multi-agent architecture where thin orchestrators (workflow files) sp

 ---

+### gsd-user-profiler
+
+**Role:** Analyzes session messages across 8 behavioral dimensions to produce a scored developer profile.
+
+| Property | Value |
+|----------|-------|
+| **Spawned by** | `/gsd:profile-user` |
+| **Parallelism** | Single instance |
+| **Tools** | Read |
+| **Model (balanced)** | Sonnet |
+| **Color** | Magenta |
+| **Produces** | `USER-PROFILE.md`, `/gsd:dev-preferences`, `CLAUDE.md` profile section |
+
+**Behavioral Dimensions:**
+Communication style, decision patterns, debugging approach, UX preferences, vendor choices, frustration triggers, learning style, explanation depth.
+
+**Key behaviors:**
+- Read-only agent — analyzes extracted session data, does not modify files
+- Produces scored dimensions with confidence levels and evidence citations
+- Questionnaire fallback when session history is unavailable
+
+---
+
 ## Agent Tool Permissions Summary

 | Agent | Read | Write | Edit | Bash | Grep | Glob | WebSearch | WebFetch | MCP |
@@ -348,6 +371,7 @@ GSD uses a multi-agent architecture where thin orchestrators (workflow files) sp
 | ui-auditor | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |
 | codebase-mapper | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |
 | debugger | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | |
+| user-profiler | ✓ | | | | | | | | |

 **Principle of Least Privilege:**
 - Checkers are read-only (no Write/Edit) — they evaluate, never modify
--- a/docs/COMMANDS.md
+++ b/docs/COMMANDS.md
@@ -424,6 +424,26 @@ Display project statistics.
 /gsd:stats                          # Project metrics dashboard
 ```

+### `/gsd:profile-user`
+
+Generate a developer behavioral profile from Claude Code session analysis across 8 dimensions (communication style, decision patterns, debugging approach, UX preferences, vendor choices, frustration triggers, learning style, explanation depth). Produces artifacts that personalize Claude's responses.
+
+| Flag | Description |
+|------|-------------|
+| `--questionnaire` | Use interactive questionnaire instead of session analysis |
+| `--refresh` | Re-analyze sessions and regenerate profile |
+
+**Generated artifacts:**
+- `USER-PROFILE.md` — Full behavioral profile
+- `/gsd:dev-preferences` command — Load preferences in any session
+- `CLAUDE.md` profile section — Auto-discovered by Claude Code
+
+```bash
+/gsd:profile-user                   # Analyze sessions and build profile
+/gsd:profile-user --questionnaire   # Interactive questionnaire fallback
+/gsd:profile-user --refresh         # Re-generate from fresh analysis
+```
+
 ### `/gsd:health`

 Validate `.planning/` directory integrity.
--- a/docs/FEATURES.md
+++ b/docs/FEATURES.md
@@ -45,6 +45,8 @@
  - [CLI Tools](#30-cli-tools)
  - [Multi-Runtime Support](#31-multi-runtime-support)
  - [Hook System](#32-hook-system)
+  - [Developer Profiling](#33-developer-profiling)
+  - [Execution Hardening](#34-execution-hardening)

 ---

@@ -769,3 +771,59 @@ fix(03-01): correct auth token expiry
 ```

 Color coding: <50% green, <65% yellow, <80% orange, ≥80% red with skull emoji
+
+### 33. Developer Profiling
+
+**Command:** `/gsd:profile-user [--questionnaire] [--refresh]`
+
+**Purpose:** Analyze Claude Code session history to build behavioral profiles across 8 dimensions, generating artifacts that personalize Claude's responses to the developer's style.
+
+**Dimensions:**
+1. Communication style (terse vs verbose, formal vs casual)
+2. Decision patterns (rapid vs deliberate, risk tolerance)
+3. Debugging approach (systematic vs intuitive, log preference)
+4. UX preferences (design sensibility, accessibility awareness)
+5. Vendor/technology choices (framework preferences, ecosystem familiarity)
+6. Frustration triggers (what causes friction in workflows)
+7. Learning style (documentation vs examples, depth preference)
+8. Explanation depth (high-level vs implementation detail)
+
+**Generated Artifacts:**
+- `USER-PROFILE.md` — Full behavioral profile with evidence citations
+- `/gsd:dev-preferences` command — Load preferences in any session
+- `CLAUDE.md` profile section — Auto-discovered by Claude Code
+
+**Flags:**
+- `--questionnaire` — Interactive questionnaire fallback when session history is unavailable
+- `--refresh` — Re-analyze sessions and regenerate profile
+
+**Pipeline Modules:**
+- `profile-pipeline.cjs` — Session scanning, message extraction, sampling
+- `profile-output.cjs` — Profile rendering, questionnaire, artifact generation
+- `gsd-user-profiler` agent — Behavioral analysis from session data
+
+**Requirements:**
+- REQ-PROF-01: Session analysis MUST cover at least 8 behavioral dimensions
+- REQ-PROF-02: Profile MUST cite evidence from actual session messages
+- REQ-PROF-03: Questionnaire MUST be available as fallback when no session history exists
+- REQ-PROF-04: Generated artifacts MUST be discoverable by Claude Code (CLAUDE.md integration)
+
+### 34. Execution Hardening
+
+**Purpose:** Three additive quality improvements to the execution pipeline that catch cross-plan failures before they cascade.
+
+**Components:**
+
+**1. Pre-Wave Dependency Check** (execute-phase)
+Before spawning wave N+1, verify key-links from prior wave artifacts exist and are wired correctly. Catches cross-plan dependency gaps before they cascade into downstream failures.
+
+**2. Cross-Plan Data Contracts — Dimension 9** (plan-checker)
+New analysis dimension that checks plans sharing data pipelines have compatible transformations. Flags when one plan strips data that another plan needs in its original form.
+
+**3. Export-Level Spot Check** (verify-phase)
+After Level 3 wiring verification passes, spot-check individual exports for actual usage. Catches dead stores that exist in wired files but are never called.
+
+**Requirements:**
+- REQ-HARD-01: Pre-wave check MUST verify key-links from all prior wave artifacts before spawning next wave
+- REQ-HARD-02: Cross-plan contract check MUST detect incompatible data transformations between plans
+- REQ-HARD-03: Export spot-check MUST identify dead stores in wired files