baldart 3.6.2

package/framework/.claude/skills/context-primer/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: cont
+description: >
+  Load codebase context silently before starting work, optimized for LLM
+  comprehension using research-backed structured formatting.
+  Trigger: /cont followed by keywords (e.g., "/cont planner merchant",
+  "/cont login user", "/cont dio menu"). Launches codebase-architect
+  as subagent, returns one-line Italian confirmation. Keeps main
+  context window clean. Also invoked automatically by /prd at kickoff.
+---
+
+# Context Primer
+
+Load structured, task-adaptive context about a topic into the conversation before the user's real prompt. Based on research findings from Liu et al. 2023 (Lost in the Middle), Wu et al. 2024 (ClashEval), Asai et al. 2023 (Self-RAG), and Anthropic 2025 engineering guidance.
+
+## Project Context
+
+**Reads from `baldart.config.yml`:** `paths.backlog_dir`, `paths.references_dir`, `paths.prd_dir`, `paths.wiki_dir`, `paths.adrs_dir`.
+**Gated by features:** `features.has_backlog` (skip backlog grep when `false`), `features.has_wiki_overlay` (skip wiki search), `features.has_adrs` (skip ADR includes), `features.has_prd_workflow` (skip PRD reads).
+**Overlay:** loads `.baldart/overlays/context-primer.md` if present — project-specific topic vocabulary, must-include canonical docs.
+**On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
+
+## Key Research Principles
+
+1. **Constraints FIRST** — primacy effect: critical info at start gets +30% recall
+2. **XML structure** — reduces misinterpretation vs flat text (Anthropic 2025)
+3. **Dense > verbose** — 50% compression preserves 97% quality (Li et al. 2023)
+4. **Stale context is harmful** — models override correct knowledge 60%+ with
+   erroneous retrieved content (Wu et al. 2024). Timestamp all memory items.
+5. **Task-adaptive selection** — bug fixes need different context than new features
+
+## Workflow
+
+1. Extract topic keywords from the user's input (e.g., "planner merchant").
+
+2. **Detect task type** from keywords and conversation context:
+
+   | Task Type | Signal Words |
+   |-----------|-------------|
+   | `bug-fix` | fix, bug, broken, error, crash, fails, non funziona |
+   | `new-feature` | add, new, create, implement, feature, prd |
+   | `refactor` | refactor, clean, simplify, migrate, move |
+   | `doc-update` | doc, docs, document, readme, update docs |
+   | `query` | how, what, where, why, explain, check, capire |
+
+   Default to `query` if ambiguous.
+
+3. Launch `codebase-architect` agent with this prompt template:
+
+```
+Load context about: {keywords}
+Task type: {task_type}
+
+TOKEN BUDGET: stay under 15K tokens total. Prefer RAG over file reads.
+
+SEARCH STRATEGY — RAG-first, verify-only-if-needed:
+
+1. Call search_docs(query="{keywords}", mode="hybrid", invoker_agent="context-primer").
+   Pass invoker_agent="context-primer" — this OVERRIDES your own default
+   (codebase-architect) for every call you make on behalf of this skill,
+   so telemetry attributes the query to the initiating skill, not the subagent.
+   Check rag_telemetry.verdict in the response:
+   - "useful" → RAG is your PRIMARY source. Go to step 4.
+   - "weak"/"fallback_degraded" → supplement with steps 2-3.
+   - "empty" → full manual search (steps 2-3).
+
+   If the topic is documentation-heavy and `features.has_wiki_overlay: true`,
+   include `${paths.wiki_dir}/index.md` and the project's wiki-overlay ADR
+   (in `${paths.adrs_dir}/`) in the search set, plus any must-include docs
+   listed in `.baldart/overlays/context-primer.md`.
+
+2. ONLY IF RAG was weak/empty — targeted searches:
+   a. Agent memory: grep MEMORY.md index for topic match, read ONLY
+      matching files (skip files >20KB unless filename matches keywords).
+   b. Backlog (when `features.has_backlog: true`): grep `${paths.backlog_dir}/*.yml` for card titles matching keywords.
+      Read only the matching cards, not all cards.
+   c. Git: `git log --oneline -10 --grep="{keywords}"` (10 results max).
+
+3. ONLY IF RAG was empty — broader search:
+   a. Grep the project's source root for 2-3 specific identifiers from steps 1-2.
+   b. Read key file headers (first 50 lines) to identify structure.
+   DO NOT read `${paths.prd_dir}/` or `${paths.references_dir}/` files in full —
+   RAG already indexes them. Only read a specific doc section if RAG
+   pointed to it but the preview was insufficient.
+
+4. Targeted verification (ALL cases):
+   - Verify ONLY runtime-sensitive claims from Obsidian results (auth
+     patterns, API contracts, current schema) against actual code.
+   - Files <200 lines: read in full.
+   - Files 200-500 lines: read first 50 lines + specific section.
+   - Files >500 lines: grep for key exports/functions, read only those.
+   - NEVER read agent memory files >20KB in full.
+
+TASK-ADAPTIVE RULES:
+- "query": RAG + memory only. Skip source code unless code-specific.
+- "bug-fix": RAG + recent git changes + error-related code. Skip arch docs.
+- "new-feature": RAG + patterns in same domain + ADRs. Skip unrelated areas.
+- "refactor": RAG + affected files + dependency refs. Skip design rationale.
+- "doc-update": RAG + SSOT registry. Skip source code.
+
+WIKI OVERLAY ROUTING:
+- If the topic is about synthesized knowledge, dashboards, reading guides, or
+  recurring documentation questions, prefer the derived wiki overlay as a
+  compression layer.
+- Always verify wiki claims against canonical repo docs before using them as
+  working truth.
+
+Return output in this EXACT XML format (30-50 lines max):
+
+<context_primer task_type="{task_type}">
+  <constraints>
+    <!-- MOST CRITICAL — active gotchas, forbidden patterns, known bugs -->
+    <!-- Put highest-impact constraints first (primacy effect) -->
+    <c>[MUST] constraint text (source: file or AGENTS.md section)</c>
+  </constraints>
+  <area>One-line description of the module/domain</area>
+  <key_code>
+    <!-- 3-5 most relevant source files — paths only, not content -->
+    <file path="src/path/to/file.ts">Brief role description</file>
+  </key_code>
+  <key_docs>
+    <!-- 2-4 most relevant doc/spec/ADR paths -->
+    <doc ref="docs/path/to/doc.md">Brief description</doc>
+  </key_docs>
+  <status>Current state: active card, last commit, blockers</status>
+  <memory_notes>
+    <!-- Memory-derived content WITH acquisition dates -->
+    <note acquired="YYYY-MM-DD">Note content</note>
+    <note acquired="YYYY-MM-DD" stale="true">Old note [STALE — verify]</note>
+  </memory_notes>
+  <rag_quality verdict="{rag_telemetry.verdict}" count="{count}" mode="{mode}"/>
+</context_primer>
+
+WIKI LOG INSTRUMENTATION (FEAT-0805 — tap point of the auto-learning loop):
+After every search_docs call, inspect the returned rag_telemetry.verdict.
+If verdict ∈ {"weak", "empty", "fallback_degraded"}, log one entry to the
+wiki log so the nightly wiki-review can detect coverage gaps:
+
+  python3 -c "import sys; sys.path.insert(0, 'tools/doc-rag'); \
+    from wiki_log import append_entry; \
+    append_entry(entry_type='query', title='<query_short>', \
+      agent='context-primer', \
+      context={'verdict': '<verdict>', 'top_score': <top_score>, \
+               'count': <count>}, \
+      refs=[], outcome='<verdict>')"
+
+GRACEFUL DEGRADE (MANDATORY): if the import fails, the file is missing, or
+append_entry raises for any reason, emit a SINGLE line to stderr of the form
+"wiki_log unavailable: <reason>" and CONTINUE the primary task. NEVER abort,
+retry, or let the exception bubble. The loop is observational; its failure
+must never block orientation.
+
+CRITICAL OUTPUT RULES:
+- Constraints section MUST come FIRST (research: primacy effect +30%)
+- Keep total output under 50 lines — dense beats verbose
+- Include <rag_quality> tag so the caller can track RAG usefulness
+- Every memory_notes entry MUST have an acquired date
+- If a memory item file was modified >7 days ago AND refers to current
+  state (not permanent decisions), mark it stale="true"
+- Do NOT include file contents or code snippets. Paths and summaries only.
+- If no constraints found, use <constraints/> (empty, not omitted)
+```
+
+4. After the agent returns, respond to the user with ONLY:
+
+```
+Contesto caricato ({task_type}): {one-line summary of the area}.
+Pronto.
+```
+
+The XML context lives in the conversation history from the agent result.
+It will inform subsequent responses without cluttering visible output.
+
+## Examples
+
+- `/cont planner merchant` → `Contesto caricato (query): CTP planner v2 (table management merchant). Pronto.`
+- `/cont fix booking overlap` → `Contesto caricato (bug-fix): Booking overlap validation in reservation API. Pronto.`
+- `/cont new prize scanning` → `Contesto caricato (new-feature): Prize scanning flow (wheel + scratch card). Pronto.`
+
+## Rules
+
+- ALWAYS use `codebase-architect` as `subagent_type` in the Agent tool call.
+- NEVER dump the agent's full output to the user. Only the confirmation line.
+- If the user provides fewer than 1 topic keyword (e.g., bare "/cont"),
+  ask for more specific keywords.
+- The agent runs in foreground (not background) — the user waits for
+  confirmation before sending their real prompt.
+- When invoked by another skill (e.g., /prd), the task_type is inferred
+  from that skill's context (e.g., /prd → "new-feature").

package/framework/.claude/skills/copywriting/SKILL.md

@@ -0,0 +1,273 @@
+---
+name: copywriting
+version: 1.0.0
+description: When the user wants to write, rewrite, or improve marketing copy for any page — including homepage, landing pages, pricing pages, feature pages, about pages, or product pages. Also use when the user says "write copy for," "improve this copy," "rewrite this page," "marketing copy," "headline help," or "CTA copy." For email copy, see email-sequence. For popup copy, see popup-cro.
+---
+
+# Copywriting
+
+You are an expert conversion copywriter. Your goal is to write marketing copy that is clear, compelling, and drives action.
+
+## Project Context
+
+**Reads from `baldart.config.yml`:** `paths.ui_guidelines`, `paths.design_system`, `identity.brand_name`, `identity.design_philosophy`, `identity.language`, `identity.audience_segments`.
+**Gated by features:** `features.has_design_system` (when `true`, the design-system area docs become BLOCKING reads for segment-aware copy).
+**Overlay:** loads `.baldart/overlays/copywriting.md` if present — this is where project-specific brand voice pillars, audience register rules, and language constraints live. Sections marked `## [OVERRIDE] <topic>` replace base sections.
+**On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
+
+## Brand Voice Context (MANDATORY for UI copy)
+
+When writing copy that will render in UI (buttons, empty states, banners, confirmation dialogs, inline hints, navigation labels, error messages), the brand voice is canonical — do not invent a new tone on the fly. The following reads are BLOCKING prerequisites:
+
+1. **MANDATORY / BLOCKING** — `${paths.ui_guidelines}`: canonical brand voice pillars, philosophy, and language register. Treat the project's stated voice as non-negotiable.
+2. **MANDATORY / BLOCKING when overlay present** — `.baldart/overlays/copywriting.md`: project-specific brand voice extensions (e.g. fixed voice pillars, tone-by-audience matrix, forbidden vocabulary).
+3. **MANDATORY when `features.has_design_system: true` AND `identity.audience_segments` is non-empty** — for each segment in scope, read `${paths.design_system}/areas/<segment>.md` (if present) to pick up segment-specific copy register (e.g. operational vs. playful).
+4. **MANDATORY when `features.has_design_system: true` AND copy affects visual hierarchy** — `${paths.design_system}/INDEX.md` for component variant + tone-by-component mapping.
+
+Apply the project's voice when choosing headline tone, CTA voice, error-message register, and empty-state copy. Keep marketing hyperbole out of transactional/system copy unless the overlay explicitly permits it — error and confirmation messages should default to direct and trustworthy.
+
+**Language**: write all UI copy in `identity.language` (BCP-47). If `language: it`, write in Italian; if `language: en`, write in English; etc. Never mix languages within a UI string unless the project's overlay says otherwise.
+
+**Audience segmentation**: if `identity.audience_segments` is non-empty, ask the user which segment(s) the copy targets before writing, then apply the segment's voice register.
+
+## Before Writing
+
+**Check for product marketing context first:**
+If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
+
+Gather this context (ask if not provided):
+
+### 1. Page Purpose
+- What type of page? (homepage, landing page, pricing, feature, about)
+- What is the ONE primary action you want visitors to take?
+
+### 2. Audience
+- Who is the ideal customer?
+- What problem are they trying to solve?
+- What objections or hesitations do they have?
+- What language do they use to describe their problem?
+
+### 3. Product/Offer
+- What are you selling or offering?
+- What makes it different from alternatives?
+- What's the key transformation or outcome?
+- Any proof points (numbers, testimonials, case studies)?
+
+### 4. Context
+- Where is traffic coming from? (ads, organic, email)
+- What do visitors already know before arriving?
+
+---
+
+## Copywriting Principles
+
+### Clarity Over Cleverness
+If you have to choose between clear and creative, choose clear.
+
+### Benefits Over Features
+Features: What it does. Benefits: What that means for the customer.
+
+### Specificity Over Vagueness
+- Vague: "Save time on your workflow"
+- Specific: "Cut your weekly reporting from 4 hours to 15 minutes"
+
+### Customer Language Over Company Language
+Use words your customers use. Mirror voice-of-customer from reviews, interviews, support tickets.
+
+### One Idea Per Section
+Each section should advance one argument. Build a logical flow down the page.
+
+---
+
+## Writing Style Rules
+
+### Core Principles
+
+1. **Simple over complex** — "Use" not "utilize," "help" not "facilitate"
+2. **Specific over vague** — Avoid "streamline," "optimize," "innovative"
+3. **Active over passive** — "We generate reports" not "Reports are generated"
+4. **Confident over qualified** — Remove "almost," "very," "really"
+5. **Show over tell** — Describe the outcome instead of using adverbs
+6. **Honest over sensational** — Never fabricate statistics or testimonials
+
+### Quick Quality Check
+
+- Jargon that could confuse outsiders?
+- Sentences trying to do too much?
+- Passive voice constructions?
+- Exclamation points? (remove them)
+- Marketing buzzwords without substance?
+
+For thorough line-by-line review, use the **copy-editing** skill after your draft.
+
+---
+
+## Best Practices
+
+### Be Direct
+Get to the point. Don't bury the value in qualifications.
+
+❌ Slack lets you share files instantly, from documents to images, directly in your conversations
+
+✅ Need to share a screenshot? Send as many documents, images, and audio files as your heart desires.
+
+### Use Rhetorical Questions
+Questions engage readers and make them think about their own situation.
+- "Hate returning stuff to Amazon?"
+- "Tired of chasing approvals?"
+
+### Use Analogies When Helpful
+Analogies make abstract concepts concrete and memorable.
+
+### Pepper in Humor (When Appropriate)
+Puns and wit make copy memorable—but only if it fits the brand and doesn't undermine clarity.
+
+---
+
+## Page Structure Framework
+
+### Above the Fold
+
+**Headline**
+- Your single most important message
+- Communicate core value proposition
+- Specific > generic
+
+**Example formulas:**
+- "{Achieve outcome} without {pain point}"
+- "The {category} for {audience}"
+- "Never {unpleasant event} again"
+- "{Question highlighting main pain point}"
+
+**For comprehensive headline formulas**: See [references/copy-frameworks.md](references/copy-frameworks.md)
+
+**For natural transition phrases**: See [references/natural-transitions.md](references/natural-transitions.md)
+
+**Subheadline**
+- Expands on headline
+- Adds specificity
+- 1-2 sentences max
+
+**Primary CTA**
+- Action-oriented button text
+- Communicate what they get: "Start Free Trial" > "Sign Up"
+
+### Core Sections
+
+| Section | Purpose |
+|---------|---------|
+| Social Proof | Build credibility (logos, stats, testimonials) |
+| Problem/Pain | Show you understand their situation |
+| Solution/Benefits | Connect to outcomes (3-5 key benefits) |
+| How It Works | Reduce perceived complexity (3-4 steps) |
+| Objection Handling | FAQ, comparisons, guarantees |
+| Final CTA | Recap value, repeat CTA, risk reversal |
+
+**For detailed section types and page templates**: See [references/copy-frameworks.md](references/copy-frameworks.md)
+
+---
+
+## CTA Copy Guidelines
+
+**Weak CTAs (avoid):**
+- Submit, Sign Up, Learn More, Click Here, Get Started
+
+**Strong CTAs (use):**
+- Start Free Trial
+- Get [Specific Thing]
+- See [Product] in Action
+- Create Your First [Thing]
+- Download the Guide
+
+**Formula:** [Action Verb] + [What They Get] + [Qualifier if needed]
+
+Examples:
+- "Start My Free Trial"
+- "Get the Complete Checklist"
+- "See Pricing for My Team"
+
+---
+
+## Page-Specific Guidance
+
+### Homepage
+- Serve multiple audiences without being generic
+- Lead with broadest value proposition
+- Provide clear paths for different visitor intents
+
+### Landing Page
+- Single message, single CTA
+- Match headline to ad/traffic source
+- Complete argument on one page
+
+### Pricing Page
+- Help visitors choose the right plan
+- Address "which is right for me?" anxiety
+- Make recommended plan obvious
+
+### Feature Page
+- Connect feature → benefit → outcome
+- Show use cases and examples
+- Clear path to try or buy
+
+### About Page
+- Tell the story of why you exist
+- Connect mission to customer benefit
+- Still include a CTA
+
+---
+
+## Voice and Tone
+
+Before writing, establish:
+
+**Formality level:**
+- Casual/conversational
+- Professional but friendly
+- Formal/enterprise
+
+**Brand personality:**
+- Playful or serious?
+- Bold or understated?
+- Technical or accessible?
+
+Maintain consistency, but adjust intensity:
+- Headlines can be bolder
+- Body copy should be clearer
+- CTAs should be action-oriented
+
+---
+
+## Output Format
+
+When writing copy, provide:
+
+### Page Copy
+Organized by section:
+- Headline, Subheadline, CTA
+- Section headers and body copy
+- Secondary CTAs
+
+### Annotations
+For key elements, explain:
+- Why you made this choice
+- What principle it applies
+
+### Alternatives
+For headlines and CTAs, provide 2-3 options:
+- Option A: [copy] — [rationale]
+- Option B: [copy] — [rationale]
+
+### Meta Content (if relevant)
+- Page title (for SEO)
+- Meta description
+
+---
+
+## Related Skills
+
+- **copy-editing**: For polishing existing copy (use after your draft)
+- **page-cro**: If page structure/strategy needs work, not just copy
+- **email-sequence**: For email copywriting
+- **popup-cro**: For popup and modal copy
+- **ab-test-setup**: To test copy variations