Refiner

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:

1. Detect Skill - Identify which skill should handle the task
2. Load Standard - Retrieve applicable quality standard from ai/standards/
3. Execute Task - Delegate to appropriate skill for initial work
4. Evaluate Output - Score work against standard (1-10 scale)
5. Refine Iteratively - Re-run skill with improvements until score >8 (max 3 iterations)
6. 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:

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

Skill Mapping:

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

Step 2: Load Quality Standard

Process:

1. Read standard file from ai/standards/[SKILL]_STANDARD.md
2. Extract evaluation metrics and scoring rubric
3. Identify minimum passing score (typically 8.0/10)
4. 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:

1. Invoke detected skill with user's original request
2. Allow skill to complete initial work
3. Capture output (file paths, content, deliverables)
4. 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:

1. Apply standard's evaluation template to output
2. Score each metric individually (0-10)
3. Calculate overall score (average of metrics)
4. Document rationale for each score
5. 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:

1. Identify 2-3 lowest-scoring metrics
2. Generate specific improvement instructions
3. Re-invoke skill with refinement guidance
4. Re-evaluate improved output
5. 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:

1. Create timestamped report in ai/refiner/refinement_[task]_[YYYYMMDD_HHMM].md
2. Document all iterations with scores
3. Include final deliverable location/content
4. Note any unresolved issues or escalations
5. 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:

1. Detect skill: ux-design
2. Load standard: UX_DESIGN_STANDARD.md (8 metrics)
3. Invoke ux-design skill with task
4. Evaluate: Likely needs 1-2 refinements (responsiveness, content clarity common issues)
5. Refine: Focus on mobile layout, Spanish content, Chilean context
6. 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:

1. Detect skill: marketing
2. Load standard: MARKETING_STANDARD.md
3. Invoke marketing skill with task
4. Evaluate: Check positioning, value prop clarity, CTA strength
5. Refine: Sharpen messaging, add ROI stats, improve CTA
6. 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:

1. Detect skill: business
2. Load standard: BUSINESS_STANDARD.md
3. Invoke business skill with task
4. Evaluate: Check data rigor, assumptions, risk analysis
5. Refine: Add sensitivity analysis, validate assumptions
6. 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:

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