git:20260919.28d30f9 to git:20260920.c4063a3

- Validate content framing using mode-specific rubrics. Two modes:

- - **writing** — Joy-grievance spectrum for human-facing content (blog posts, emails, articles). Evaluates whether content frames experiences through curiosity and generosity rather than grievance and accusation.

- - **instruction** — Positive framing validation for LLM-facing content (agents, skills, pipelines). Evaluates whether instructions tell the reader what to do rather than what to avoid (ADR-127).

- By default the skill evaluates each paragraph/instruction independently, produces a score (0-100), and suggests reframes without modifying content. Optional flags: `--fix` rewrites flagged items in place and re-verifies; `--strict` fails on any item below 60; `--mode writing|instruction` overrides auto-detection.

- This skill checks *framing*, not *topic* and not *voice*. Voice fidelity belongs to voice-validator, AI pattern detection belongs to the private de-AI editor skill.

- ## Deep References

- | When | Load | Content |

- | Scoring instruction files (agents, skills, pipelines) | `references/instruction-rubric.md` | Positive-framing patterns, rewrite rules, scoring, examples |

- | Scoring human-facing prose (blog posts, emails, docs) | `references/writing-rubric.md` | Joy-grievance spectrum, subtle patterns, scoring, examples |

- **Goal**: Determine which rubric to apply based on file location or explicit flag.

-

- **Auto-detection rules** (in priority order):

- 1. Explicit `--mode writing|instruction` flag → use that mode

- 2. File in `agents/*.md` → **instruction**

- 3. File in `skills/*/SKILL.md` → **instruction**

- 4. File in `skills/workflow/references/*.md` → **instruction**

- 5. File is `CLAUDE.md` or `README.md` → **instruction**

- **Load the rubric**: Read `references/{mode}-rubric.md` for the scoring criteria, patterns, and examples relevant to this mode.

- **GATE**: Mode determined, rubric loaded. Proceed to Phase 1.

- **Goal**: Use regex scanning as a fast gate to catch obvious patterns before spending LLM tokens on semantic analysis.

- **For writing mode**: Run the regex-based scanner for grievance patterns:

- **For instruction mode**: Run a grep scan for prohibition patterns:

- **Handle hits**: Report findings with suggested reframes from the loaded rubric. If `--fix` mode is active, apply reframes and re-run to confirm clean.

- **GATE**: Regex/grep scan returns zero hits. Resolve obvious patterns before proceeding to Phase 2 — mechanical fixes come first.

- **Goal**: Read the content and evaluate each item against the loaded rubric using LLM semantic understanding.

-

- **Step 1: Read the content**

-

- Read the full file. Skip frontmatter (YAML between `---` markers) and code blocks.

- - **Writing mode**: Identify paragraph boundaries (blank-line separated blocks). Skip blockquotes.

- - **Instruction mode**: Identify each instructional statement — bullet points, table cells, imperative sentences, section headings. Skip examples, code blocks, quoted user dialogue, and file path references.

- **Step 2: Evaluate against the rubric**

- Apply the scoring dimensions from the loaded rubric (`references/{mode}-rubric.md`). Each rubric defines its own PASS/FAIL dimensions, subtle patterns to detect, and contextual exceptions.

- For **writing mode**: Evaluate through the joy-grievance lens. Watch for the subtle patterns described in `references/writing-rubric.md` (defensive disclaimers, accumulative grievance, passive-aggressive factuality, reluctant generosity).

- For **instruction mode**: Evaluate through the positive-negative lens. Check each instruction against the patterns table in `references/instruction-rubric.md`. Apply contextual exceptions — subordinate negatives attached to positive instructions are PASS, as are negatives in code examples, writing samples, and technical terms.

- Apply the scoring scale from the loaded rubric. For any item scoring in the lower tiers (CAUTION/GRIEVANCE for writing, NEGATIVE-LEANING/PROHIBITION-HEAVY for instruction), draft a specific reframe suggestion that preserves the substance while shifting the framing.

- When an item seems subtle enough to question flagging — that is precisely when flagging matters most. Subtle patterns are what the regex/grep pre-filter misses, making them the primary purpose of this LLM analysis phase.

- **GATE**: All items analyzed and scored. Reframe suggestions drafted for all flagged items. Proceed to Phase 3.

- **Goal**: Produce a structured report with scores, findings, and reframe suggestions.

-

- Average all item scores. Pass criteria come from the loaded rubric:

- - **Writing mode**: Score >= 60 AND no GRIEVANCE paragraphs

- - **Instruction mode**: Score = 100 AND zero primary negative patterns in instructional context

- **Step 2: Output the report**

- **Step 3: Handle fix mode**

- If `--fix` mode is active:

- 1. Rewrite flagged items using the drafted reframe suggestions

- 2. Preserve the substance — change only the framing

- 3. Re-run Phase 2 analysis on rewritten items to verify fixes landed

- 4. If fixes introduce new flagged items, iterate (maximum 3 attempts)

- **GATE**: Report produced. If `--fix`, all rewrites applied and re-verified. Joy check complete.

- This skill integrates with content and toolkit pipelines:

-

- **Writing pipeline** (human-facing content):

- CONTENT --> voice-validator --> scan-ai-patterns --> joy-check --mode writing --> de-AI edit (private skill)

- **Instruction pipeline** (agent/skill/pipeline creation and modification):

- - `skill-creator` pipeline: Call the Skill tool with `joy-check`. Use instruction mode after generating a new skill.

- - `agent-upgrade` pipeline: Call the Skill tool with `joy-check`. Use instruction mode after modifying an agent.

- - `voice-writer`: Call the Skill tool with `joy-check`. Use writing mode during validation.

- - `doc-pipeline`: Call the Skill tool with `joy-check`. Use instruction mode for toolkit documentation.

- The joy-check can be invoked standalone via `/joy-check [file]` (auto-detects mode) or with explicit `--mode writing|instruction`.

- **Cause**: Path incorrect or file does not exist

- **Solution**:

- 1. Verify path with `ls -la [path]`

- 2. Use glob pattern to search: `Glob **/*.md`

- 3. Confirm correct working directory

- **Cause**: `scan-negative-framing.py` script missing or Python error

- **Solution**:

- 1. Verify script exists: `ls scripts/scan-negative-framing.py`

- 2. Check Python version: `python3 --version` (requires 3.10+)

- 3. If script unavailable, skip Phase 1 and proceed directly to Phase 2 LLM analysis -- the regex pre-filter is an optimization, not a requirement

- **Cause**: Content is fundamentally framed through grievance -- not recoverable with paragraph-level reframes

- **Solution**:

- 1. Report the scores honestly

- 2. Suggest the content needs a full rewrite with a different framing premise, not paragraph-level fixes

- 3. Point the user to the Joy Principle section and Examples for guidance on the target framing

- **Cause**: Rewritten paragraphs keep introducing new CAUTION/GRIEVANCE patterns, often because the underlying premise is grievance-based

- **Solution**:

- 1. Output the best version achieved with flagged remaining concerns

- 2. Explain which specific rubric dimensions resist correction

- 3. Suggest the framing premise itself may need rethinking, not just the language

- - `references/writing-rubric.md` — Joy-grievance spectrum, subtle patterns, scoring, examples (writing mode)

- - `references/instruction-rubric.md` — Positive framing rules, patterns to flag, rewrite strategies, examples (instruction mode)

- - `voice-validator` — Voice fidelity validation (different concern)

- - private de-AI editor skill — AI pattern detection and removal (different concern; installed from `~/private-skills`)

- - `voice-writer` — Content pipeline that invokes joy-check as a validation phase

- - `skill-creator` — Skill creation pipeline that invokes joy-check in instruction mode