golem15/msd-core
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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
This commit is contained in:
Tom Boucher
2026-03-16 15:39:52 -04:00
committed by GitHub
parent 460f92e727
commit 80605d2051
5 changed files with 113 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
docs/AGENTS.md
View File

@@ -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

20
docs/COMMANDS.md
View File

@@ -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.

58
docs/FEATURES.md
View File

@@ -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