Repository navigation
Releases: WeMakeGood/generating-audience-profiles
Releases · WeMakeGood/generating-audience-profiles
Release list
v1.0.0
First release. The skill was built and then refined across five iteration rounds against a complete real-world build through Phase 4; the sections below record what each round changed and why, since every one of them is a behavioral difference a user of 1.0.0 inherits.
Added (round 5 — based on the complete SCL build through Phase 4)
- Matrix Structure Variants section in ARCHITECTURE.md. Documents three matrix structural options: default single rectangular 2D grid, Variant A (single matrix with non-rectangular coverage when 1–2 audience-kinds have intentionally empty cells), and Variant B (two related 2D matrices with row-specific column names when a substantive subset of audience-kinds operates on decision shapes the default column dimension would distort). Includes a Phase 3 decision protocol (three questions about audience-kind fit, misleading-column-label risk, and substantive-subset coherence) for choosing between the three options. The SCL build committed to Variant B at Phase 3 STOP; the variant was previously available as a brief aside in the Suggested Default Dimensions section but lacked first-class architectural documentation.
- Phase 3 Step 2.5 (Matrix-structure decision). New step in PHASE_3_DESIGN.md after Step 2 dimension commitment and before Step 3 grid construction. Applies the Matrix Structure Variants decision protocol explicitly, requires the proposed structure and reasoning to be logged to process-log.md, and adds an explicit user-confirmation gate before grid construction begins. Variant B requires presenting both the Variant B structure and the Variant A equivalent for comparison so the user commits knowingly to the documentation overhead.
- Per-cell module-length budget set in Pass 2 agent-needs. PHASE_2_COMPREHEND.md Step 8 now requires per-cell length budgets to be set explicitly in agent-needs.md based on cell complexity (simple / standard / cross-audience-leverage / modeled-only / sub-structured). PHASE_4_BUILD.md length-target language updated to point at the per-cell budget rather than hard-coding 200–600 words. ARCHITECTURE.md Sub-Profile Module Shape section updated to acknowledge that complex matrices may run 700–1100 words per cell with documented justification. The SCL build's modules ran 800–1100 words; the agent flagged the deviation in agent-needs.md but the discipline wasn't structural — round 5 makes it structural.
- Challenge-inviting questions in Phase 1 STOP and Pass 1 STOP. Both STOPs now have a separate "Challenge questions" subsection alongside the existing confirmation questions. Phase 1 STOP challenge questions invite the user to surface audience candidates the assessment missed, confidence-overruns the agent didn't catch, and explicit-framing differences that feel productive vs. overreaches. Pass 1 STOP challenge questions invite the user to identify refinements that surprise vs. seem too confident, confirmations that may be confirmation-bias rather than source-tested, conflicts the user knows are already resolved, and sources the agent under- or over-weighted. Confirmation questions establish agreement; challenge questions tell the next phase which findings to test hardest.
- Modeled-data references verifiability scan in Pass 2 GATE. PHASE_2_COMPREHEND.md GATE for Pass 2 now requires an explicit scan of each modeled-data picture's Identifiable References list for the vague-organization-name-without-specific-study failure pattern. Vague gestures must be either replaced with specific verifiable citations or marked as explicit "model inference from aggregated training data." Closes the discipline-drift gap that the SCL build exposed at user review (the rule existed in PHASE_2 Step 5 but had no structural check until round 5).
- Audience-matrix.md template updated to support all three matrix structure variants. Template now includes a Matrix Structure section where the build records which variant was committed and a separate matrix-presentation block for Variant B's two-matrix layout with row-specific columns.
Observations from the complete SCL build (not skill edits, just notes)
- Phase 4's per-module protocol scaled cleanly to 35 modules across two related 2D matrices with 0 regenerations needed. The Runtime Frame Set + Substantive Source Surface + write + self-check sequence is doing the work upstream at the planning step, before any prose is written. This is evidence the architecture is sound at scale.
- The runtime-frame contamination scan against build-perspective phrases ("the research showed," "compared to other cells," etc.) returned zero matches across all 35 modules. The discipline holds architecturally.
- Modeled-only and thin status flags in module bodies (not just matrix-level) gave the downstream runtime agent immediate context for module reliability. This is the correct shape and worth preserving as the discipline becomes more familiar to skill users.
Changed (round 4 — based on the third SCL test run)
- Tightened the candidates-layer citation prohibition with named failure patterns. Round 3's rule said "no specific source citations" but defined citation too narrowly (statistics and revenue figures only). The third SCL test run produced a candidates layer with named events ("the principals' May 2026 US Sumo Open scouting trip"), named peer-org playbooks ("PBR's endemic-then-mainstream sequence," "ANW's city qualifiers"), and specific sector references ("(Sectors 02, 04, 08)") — and the agent's GATE scan reported "none flagged" because none of those matched its definition of citation. The fix names four failure patterns explicitly: (a) numerical evidence, (b) named events/dates/properties from sources, (c) named peer organizations/playbooks/specific examples, (d) specific sector references in candidate-field prose. The source-set-expectation field remains the one place where class-and-sector reference is allowed, with no content extraction from named dossiers. Mirrors the allowed/disallowed verb-pattern shape that worked for the source-index rule in round 3.
- Phase 1 GATE candidates-layer scan now lists the four patterns explicitly. The scan is no longer "did you check for citations" but "did you check for these four specific patterns, and report any matches." Removes the discretion that allowed the third run's scan to pass despite real violations.
Added (round 3 — based on the second SCL test run)
- Structural-claim discipline in PHASE_1_SETUP.md Step 3. Replaces the unenforceable "do not extract audience content from sources" instruction with allowed/disallowed verb patterns the agent can test against. The agent reads each source fully (required for accurate classification), but the source-index entry must stay at structural identity ("Peer-org dossier following the standard format" — allowed; "Documents the family audience as unclaimed white space" — disallowed because the claim could only be made after reading for substance). Acknowledges honestly that once content is read it is in working memory, and locates the discipline at the entry-writing layer rather than at the reading layer.
- Two-layer audience-needs assessment. Sections A (purpose) and B (operating environment) are the framing layer — depth and source citations appropriate. Sections C (candidates) and D (comparison) are the candidates layer — compressed, uncited, sketch-depth. The candidates layer has hard constraints: 1–2 sentences per field, no specific source citations, roughly equivalent depth across candidates. Pass 1 grounds the candidates; over-deep Phase 1 candidates anchor Pass 1 and waste work when Pass 1 refines them.
- Phase 1 GATE scans both failure modes. Explicit checks: (1) scan every source-index entry for disallowed verb patterns; (2) scan every audience candidate for source citations and length violations. Flagged entries must be fixed before STOP — known-contaminated artifacts cannot be presented to the user.
Changed (round 3)
- Updated CRITICAL RULES block at top of PHASE_1_SETUP.md to reflect the two-layer assessment and structural-claim discipline.
- Refined ANALYTICAL POSTURE rule in SKILL.md to describe the two-layer assessment structure.
- Refined SOURCE-INDEX HYGIENE rule in SKILL.md with the structural-claim test.
- Added two new entries to SKILL.md
<failed_attempts>: source-index entries that describe what a source says (even after a full read), and audience-needs assessments over-grounded in source content. - Updated
templates/source-index.mdwith the allowed/disallowed verb patterns from Step 3.
Added (round 2)
- ANALYTICAL POSTURE rule (SKILL.md Critical Rules). Names the skill's analytical work as a first-class discipline — the agent's job is to produce audience definitions derived from organizational context, not to extract audience labels from what sources or the user's framing already name. Drawn from a real test failure: the agent ran Phase 1 as inventory + extraction, never doing analytical work on what audiences the organization actually needed to engage, and built expectations around source-named targets.
- Phase 1 Step 4 (Initial audience-needs assessment). New analytical step in Phase 1 producing: (a) the organization's purpose as inferred from the audience question and source-set structure, (b) the operating environment, (c) 4–8 audience candidates with rationale tied to the purpose, and (d) a comparison to what the audience question and source set explicitly name. The assessment surfaces audiences the explicit framing misses or disaggregates audiences the framing collapses. Initial expectations are written against this assessment, not against source-named targets.
- Phase 1 STOP (Phase 1 Review). Phase 1 now ends with a user review of source classifications, the audience-needs assessment, initial expectations, and BLOCKING gaps — before Phase 2 begins. Mirrors the building-context-libraries Phase 1 STOP pattern.
- **Phase 2 Pass 1 Step 0 (Load Al...