GabeDA Refiner Skill

Purpose

This skill acts as a quality assurance orchestrator that ensures outputs from other skills meet production standards through systematic evaluation and iterative refinement.

Core Functions:

Detect Skill - Identify which skill should handle the task
Load Standard - Retrieve applicable quality standard from ai/standards/
Execute Task - Delegate to appropriate skill for initial work
Evaluate Output - Score work against standard (1-10 scale)
Refine Iteratively - Re-run skill with improvements until score >8 (max 3 iterations)
Document Results - Generate refinement report in ai/refiner/

When to Use This Skill

Invoke this skill when:

Work requires quality assurance against a defined standard
Initial output quality is uncertain or needs validation
Task requires iterative refinement until meeting threshold
Need documented evaluation of work quality
Producing customer-facing deliverables (landing pages, reports, dashboards)
Creating production-ready artifacts (code, documentation, designs)

NOT for:

Tasks without defined standards
Quick prototypes or MVPs (where 8/10 quality not required)
Tasks that don't involve other skills
Exploratory research (no clear quality metrics)

Core Workflow

Step 1: Analyze Task and Detect Skill

Process:

Parse user request to understand deliverable type
Map deliverable to responsible skill
Identify applicable standard from ai/standards/

Skill Mapping:

| Deliverable Type | Primary Skill | Standard | |------------------|---------------|----------| | Webpage design, mockup, wireframe | ux-design | UX_DESIGN_STANDARD.md | | Marketing copy, landing page, campaign | marketing | MARKETING_STANDARD.md | | Business case, user research, ROI analysis | business | BUSINESS_STANDARD.md | | Implementation plan, architecture, code | architect | ARCHITECT_STANDARD.md | | Strategic plan, requirements, decision | executive | EXECUTIVE_STANDARD.md | | Notebook, dashboard, visualization | insights | INSIGHTS_STANDARD.md |

For detailed skill detection logic: See references/skill_detection_rules.md

Step 2: Load Quality Standard

Process:

Read standard file from ai/standards/[SKILL]_STANDARD.md
Extract evaluation metrics and scoring rubric
Identify minimum passing score (typically 8.0/10)
Note any constraints (e.g., "no metric below 6/10")

Standard Structure: All standards follow consistent format:

Metrics: 6-8 measurable dimensions with 0-10 scoring
Passing Score: Typically 8.0/10 average
Evaluation Template: Structured scoring format
Refinement Guidance: Common issues and fixes

For standard interpretation guide: See references/standard_interpretation.md

Step 3: Execute Task with Skill

Process:

Invoke detected skill with user's original request
Allow skill to complete initial work
Capture output (file paths, content, deliverables)
Prepare output for evaluation

Invocation Format:

Skill([skill-name])

[User's original request - pass through verbatim]

[Additional context if needed]

Notes:

Pass user request verbatim to skill (don't modify or interpret)
Skills may create files, generate content, or produce artifacts
Track all outputs for evaluation

Step 4: Evaluate Against Standard

Process:

Apply standard's evaluation template to output
Score each metric individually (0-10)
Calculate overall score (average of metrics)
Document rationale for each score
Identify lowest-scoring metrics for improvement

Evaluation Structure:

## Iteration [N] Evaluation

**Output:** [What was produced]
**Standard:** [Which standard applied]
**Date:** [YYYY-MM-DD]

### Scores

| Metric | Score | Rationale |
|--------|-------|-----------|
| [Metric 1] | X/10 | [Why this score] |
| [Metric 2] | X/10 | [Why this score] |
| ... | ... | ... |

**Overall Score:** XX/10

**Status:** [✅ PASS (>8.0) / 🟡 REFINE (≤8.0) / ❌ FAIL (<6.0)]

For detailed evaluation guide: See references/evaluation_methodology.md

Step 5: Refine Until Quality Threshold Met

Decision Logic:

If Score > 8.0: ✅ PASS → Proceed to Step 6 (document results)

If Score ≤ 8.0: 🟡 REFINE → Iterate:

Identify 2-3 lowest-scoring metrics
Generate specific improvement instructions
Re-invoke skill with refinement guidance
Re-evaluate improved output
Repeat up to max 3 total iterations

If Score < 6.0 after 3 iterations: ❌ ESCALATE → Invoke executive skill for guidance

Refinement Format:

Skill([skill-name])

**Refinement Request - Iteration [N+1]**

**Previous Output:** [Link/description]
**Current Score:** X.X/10 (needs >8.0)

**Areas Needing Improvement:**
1. [Metric Name] (scored X/10) - [Specific issue]
   - **Fix:** [Concrete action to take]
2. [Metric Name] (scored X/10) - [Specific issue]
   - **Fix:** [Concrete action to take]

**Standard Reference:** ai/standards/[STANDARD].md

Please refine the output focusing on these areas.

Iteration Limits:

Max 3 iterations total (initial + 2 refinements)
After 3 iterations:
- If score >8.0: Document success
- If score ≤8.0: Escalate to executive, document partial success with recommendations

For refinement strategies: See references/refinement_strategies.md

Step 6: Generate Refinement Report

Process:

Create timestamped report in ai/refiner/refinement_[task]_[YYYYMMDD_HHMM].md
Document all iterations with scores
Include final deliverable location/content
Note any unresolved issues or escalations
Provide recommendations for future improvements

Report Structure:

# Refinement Report: [Task Name]

**Date:** [YYYY-MM-DD HH:MM]
**Skill Used:** [skill-name]
**Standard Applied:** [STANDARD_NAME]
**Iterations:** [N] of 3

---

## Summary

**Task:** [User's original request]
**Final Score:** X.X/10 [✅ PASS / 🟡 PARTIAL / ❌ ESCALATED]
**Output Location:** [File path or description]

---

## Iteration History

### Iteration 1: Initial Output
- **Score:** X.X/10
- **Status:** [PASS/REFINE]
- **Metrics:** [Breakdown]
- **Issues:** [What needed improvement]

### Iteration 2: First Refinement (if needed)
- **Score:** X.X/10
- **Status:** [PASS/REFINE]
- **Improvements:** [What changed]
- **Remaining Issues:** [If any]

### Iteration 3: Second Refinement (if needed)
- **Score:** X.X/10
- **Status:** [PASS/REFINE/ESCALATED]
- **Improvements:** [What changed]
- **Final Issues:** [If any]

---

## Final Evaluation

[Complete scoring breakdown from final iteration]

---

## Deliverable

**Location:** [File path or link]
**Quality Level:** [Production-ready / Needs minor fixes / Requires major revision]

---

## Recommendations

**For This Task:**
- [Any remaining improvements for user to consider]

**For Future Similar Tasks:**
- [Patterns noticed that could improve first-iteration quality]

---

**Report Status:** [Complete / Escalated to Executive]

Template: assets/templates/refinement_report_template.md

Skill Integration

From Executive Skill

Receives: Strategic tasks requiring quality assurance
Returns: Quality-assured deliverables with evaluation reports

To All Skills

Provides: Task delegation with quality requirements
Requests: Initial work and refinements
Monitors: Quality progression through iterations

To Executive Skill (Escalation)

Triggers: Score <6.0 after 3 iterations
Provides: Refinement history, blockers, recommendations
Requests: Strategic guidance or requirement adjustment

Common Patterns

Pattern 1: Landing Page Design (ux-design)

Task: "Create landing page for Chilean SMB market"

Process:

Detect skill: ux-design
Load standard: UX_DESIGN_STANDARD.md (8 metrics)
Invoke ux-design skill with task
Evaluate: Likely needs 1-2 refinements (responsiveness, content clarity common issues)
Refine: Focus on mobile layout, Spanish content, Chilean context
Document: Report in ai/refiner/refinement_landing_page_chile_[timestamp].md

Expected Iterations: 2 (first draft 7.5/10, refined 8.5/10)

Pattern 2: Marketing Campaign Copy (marketing)

Task: "Write launch email for new retention feature"

Process:

Detect skill: marketing
Load standard: MARKETING_STANDARD.md
Invoke marketing skill with task
Evaluate: Check positioning, value prop clarity, CTA strength
Refine: Sharpen messaging, add ROI stats, improve CTA
Document: Report in ai/refiner/refinement_launch_email_[timestamp].md

Expected Iterations: 1-2 (first draft typically 7.5-8.5/10)

Pattern 3: Business Case Analysis (business)

Task: "Analyze ROI for Chilean market expansion"

Process:

Detect skill: business
Load standard: BUSINESS_STANDARD.md
Invoke business skill with task
Evaluate: Check data rigor, assumptions, risk analysis
Refine: Add sensitivity analysis, validate assumptions
Document: Report in ai/refiner/refinement_chile_roi_[timestamp].md

Expected Iterations: 1 (business skill typically produces 8.5+/10 on first pass)

Working Directory

Refiner Workspace: .claude/skills/refiner/

Bundled Resources:

references/skill_detection_rules.md - Mapping deliverables to skills
references/standard_interpretation.md - How to read and apply standards
references/evaluation_methodology.md - Scoring guidelines and calibration
references/refinement_strategies.md - Common issues and fixes per skill
assets/templates/refinement_report_template.md - Standard report format
assets/examples/ - Complete refinement examples (3 patterns)

Quality Standards (Reference):

/ai/standards/UX_DESIGN_STANDARD.md - 8 metrics for UX work
/ai/standards/MARKETING_STANDARD.md - Marketing quality metrics
/ai/standards/BUSINESS_STANDARD.md - Business rigor metrics
/ai/standards/ARCHITECT_STANDARD.md - Code quality metrics
/ai/standards/EXECUTIVE_STANDARD.md - Strategic work metrics
/ai/standards/INSIGHTS_STANDARD.md - Analysis quality metrics

Output Reports (Create Here):

/ai/refiner/refinement_[task]_[YYYYMMDD_HHMM].md - Timestamped reports

Living Documents (Append Only):

/ai/SKILLS_MANAGEMENT.md - Track refinement patterns and skill quality trends

Quality Assurance Principles

1. Standards-Based Evaluation

Principle: All evaluation uses objective, documented standards (not subjective opinion).

Application:

Every score must reference specific standard criteria
Rationale must cite standard examples or checklists
No "I think" or "feels like" - only "standard requires" or "checklist shows"

2. Constructive Refinement

Principle: Refinement requests provide actionable guidance (not vague criticism).

Bad Example: ❌ "Typography needs improvement" Good Example: ✅ "Typography scored 7/10. Issues: Body text is 14px (standard requires 16px+). Fix: Increase body text to 16px."

3. Iteration Efficiency

Principle: Each refinement focuses on 2-3 highest-impact improvements (not everything at once).

Strategy:

Iteration 1 → Fix lowest-scoring metric
Iteration 2 → Fix next 2 lowest metrics
Iteration 3 → Polish and edge cases

4. Escalation Discipline

Principle: Escalate when blocked, not when impatient.

Escalate when:

Score <6.0 after 3 iterations (quality floor not met)
Standard unclear or contradictory (need guidance)
Task requirements conflict with standard (strategic decision needed)

Don't escalate when:

Just need one more iteration (but already at max 3)
Want to try different skill (refiner chooses skill, not user)

Examples

Example 1: UX Design Refinement

Task: "Design landing page for GabeDA Chilean market"

Iteration 1:

ux-design creates initial design
Score: 7.8/10 (mobile responsiveness 7/10, content clarity 7/10)
Refine: Increase touch targets to 44px, translate to Spanish, add Chilean currency examples

Iteration 2:

ux-design refines with improvements
Score: 8.6/10 (all metrics 8+)
✅ PASS - Report generated

Full Example: assets/examples/example_ux_refinement.md

Example 2: Marketing Copy Refinement

Task: "Write email announcing customer retention feature"

Iteration 1:

marketing creates initial email
Score: 7.5/10 (value prop 7/10, CTA 7/10)
Refine: Add specific ROI stat ("250:1 ROI for Chilean SMBs"), strengthen CTA ("Start Free Trial" vs "Learn More")

Iteration 2:

marketing refines with improvements
Score: 8.4/10 (all metrics 8+)
✅ PASS - Report generated

Full Example: assets/examples/example_marketing_refinement.md

Example 3: Escalation Scenario

Task: "Create real-time anomaly detection dashboard"

Iteration 1:

insights creates initial dashboard
Score: 5.2/10 (technical complexity too high for target audience)

Iteration 2:

insights simplifies dashboard
Score: 6.8/10 (still too technical)

Iteration 3:

insights further simplifies
Score: 7.2/10 (can't reach 8+ without changing requirements)

Escalation:

Invoke executive skill: "Target audience (small business owners) conflicts with feature complexity (real-time ML). Recommend: Simplify to daily anomaly alerts (not real-time)."

Full Example: assets/examples/example_escalation.md

Version History

v1.0.0 (2025-10-30)

Initial version with 6-step refinement workflow
Skill detection, standard loading, iterative evaluation
Max 3 iterations, escalation to executive if needed
Timestamped reports in ai/refiner/

Last Updated: 2025-10-30 Core Principles:

Objective evaluation - Standards-based, not opinion-based
Actionable refinement - Specific fixes, not vague feedback
Iteration efficiency - Focus on highest-impact improvements
Quality floor - 8.0/10 minimum for production work
Escalation discipline - Escalate blockers, not impatience