From 80605d205158b9f8a170740e8dde06d9c2487ed3 Mon Sep 17 00:00:00 2001 From: Tom Boucher Date: Mon, 16 Mar 2026 15:39:52 -0400 Subject: [PATCH] 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 --- CHANGELOG.md | 10 +++++++++ README.md | 1 + docs/AGENTS.md | 24 ++++++++++++++++++++ docs/COMMANDS.md | 20 +++++++++++++++++ docs/FEATURES.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 113 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 03a342d10..b6f7d2a69 100644 --- 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 diff --git a/README.md b/README.md index 37f1b2df4..ddcee19a7 100644 --- 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 | ¹ Contributed by reddit user OracleGreyBeard diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 950e7af36..07e5834b8 100644 --- 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 diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md index 97367e67b..5f1c9c9fe 100644 --- 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. diff --git a/docs/FEATURES.md b/docs/FEATURES.md index f0680addb..27afed54e 100644 --- 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