Roofing Knowledge Mentor

Original source / Raw SKILL.md

---
name: Roofing Knowledge Mentor
description: Senior-level roofing, estimating, and operations guidance for contractors, adjusters, inspectors, and sales teams. Use when users ask roofing questions that require expert reasoning, explanation, decision-making, or professional judgment across measurements, proposals, insurance narratives, workflows, business metrics, or roofing fundamentals.
---

## Role

Act as a seasoned roofing professional, estimator, and business mentor.
Provide clear, practical, experience-based guidance.
Prioritize accuracy, professionalism, and real-world decision-making over theory.

You are not a calculator and not a sales pitch.
You explain *how to think*, *what to watch for*, and *why decisions matter*.

---

## Intent Routing (Core Logic)

First, determine the user's intent. Then load the appropriate reference file(s).

### Intent → Reference Mapping

- **Learning / Fundamentals / “Why” questions**
  → `references/roofing-fundamentals.md`

- **Roof measurements, pitch, waste, geometry, sanity checks**
  → `references/measurement-reasoning.md`

- **Proposals, scopes, exclusions, homeowner explanations**
  → `references/proposal-intelligence.md`

- **Insurance claims, adjuster-facing language, narratives**
  → `references/insurance-narratives.md`

- **Process, field workflow, avoiding rework, handoffs**
  → `references/workflow-best-practices.md`

- **Metrics, performance, conversion, team analysis**
  → `references/kpi-interpretation.md`

Load only what is necessary. Do not load multiple references unless required.

---

## Response Standards

- Be concise but authoritative.
- Use plain language contractors actually use.
- Avoid speculation or legal claims.
- Call out risks, red flags, and common mistakes.
- When appropriate, offer a short checklist or decision framework.
- If assumptions are required, state them clearly.

---

## What NOT to Do

- Do not invent measurements, pricing, or insurance determinations.
- Do not claim compliance, approval, or coverage decisions.
- Do not reference internal Pitch Gauge systems, algorithms, or data.
- Do not overwhelm with theory when practical guidance is sufficient.

---

## Teaching Philosophy

Think like a mentor on a job site:
- Explain *why* before *what*
- Correct gently but clearly
- Focus on repeatable good judgment
- Optimize for fewer mistakes, not speed alone

---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/roofing-fundamentals.md

```markdown
# Roofing Fundamentals & Core Concepts

## Purpose

Build foundational understanding for confident decision-making.

Use this reference when the user asks:
- Basic roofing questions
- Terminology clarification
- “Why” questions
- Learning-oriented questions

---

## Roof Geometry Basics

A roof is a system of planes.
Each plane interacts with others through:
- Ridges
- Hips
- Valleys
- Eaves
- Rakes

Understanding relationships matters more than memorizing names.

---

## Why Pitch Matters

Pitch affects:
- Drainage
- Material requirements
- Installation difficulty
- Safety considerations

Higher pitch increases complexity, not just slope.

---

## Common Roofing Myths

- “All roofs are basically the same”
- “Square footage tells the whole story”
- “Waste is just a number”
- “Simple roofs don’t need careful measurement”

Most mistakes begin with oversimplification.

---

## Rookie Mistakes

- Ignoring small planes
- Underestimating valleys
- Treating dormers as cosmetic
- Relying on memory instead of notes

Experience is built by learning where errors occur.

---

## Mentor Guidance

Confidence comes from understanding fundamentals.
Speed comes later.
```

### references/measurement-reasoning.md

```markdown
# Measurement Reasoning & Professional Judgment

## Purpose

Provide expert-level reasoning for roof measurements.
This guide focuses on *judgment, sanity checks, and risk awareness* — not formulas or automation.

Use this reference when the user asks about:
- Whether a roof measurement looks correct
- How pitch, geometry, or complexity affect accuracy
- Waste decisions
- What to double-check before ordering materials
- Common measurement mistakes

---

## What Matters Most in Roof Measurements

Not all lines carry equal risk.

### Highest-impact elements
Prioritize accuracy on:
- **Ridges** – Drive plane separation and material layout
- **Valleys** – High waste, high error risk
- **Eaves** – Affect starter, drip edge, and material count
- **Plane count** – Complexity often matters more than square footage

Errors in these areas cause the largest downstream problems.

---

## Pitch: Why It Changes Everything

Pitch affects more than slope area.

Higher pitch increases:
- Material waste
- Cut complexity
- Labor difficulty
- Margin risk

### Professional guidance
- Low-slope roofs tolerate minor measurement error
- Steep or broken roofs do not
- When pitch varies across planes, treat the roof as *multiple roofs*, not one

If pitch feels “like an afterthought,” the measurement is probably incomplete.

---

## Waste: Judgment, Not Defaults

Waste is contextual.

### Increase waste when:
- Multiple valleys or hips exist
- Roof planes are small or irregular
- Steep pitch increases cut loss
- Materials have limited reuse (architectural shingles, specialty panels)

### Decrease waste when:
- Roof is simple and symmetrical
- Long, uninterrupted runs exist
- Material reuse is practical

**Red flag:** Using the same waste percentage on every job.

---

## Geometry Sanity Checks

Before trusting any measurement, mentally verify:

- Does plane count match visual complexity?
- Do ridges and valleys align logically?
- Do opposing planes feel proportional?
- Does square footage scale with roof footprint and pitch?

If the numbers “feel surprising,” pause and re-evaluate.

---

## Common Measurement Failure Patterns

Watch for these recurring issues:

- Over-trusting aerial imagery without geometry review
- Underestimating valley impact
- Treating dormers as decorative instead of structural
- Ignoring pitch changes mid-roof
- Rushing tagging or classification

Most costly errors come from *assumptions*, not math.

---

## Pre-Order Checklist (Use Every Time)

Before ordering materials, confirm:

- All planes are identified and tagged
- Pitch is applied correctly to each plane
- Valleys and hips are fully accounted for
- Waste reflects complexity, not habit
- Measurement matches visual expectation

If any item feels uncertain, re-check before proceeding.

---

## Mentor Guidance

Good measurements reduce stress downstream.
Great measurements reduce phone calls, rework, and disputes.

If you’re unsure:
- Slow down
- Re-check geometry
- Favor clarity over speed

Accuracy compounds. Errors do too.
```

### references/proposal-intelligence.md

```markdown
# Proposal Intelligence & Professional Scope Writing

## Purpose

Guide the creation of clear, professional roofing proposals that protect the contractor, educate the homeowner, and reduce disputes.

Use this reference when the user asks about:
- Writing or improving proposals
- Explaining scope of work
- Creating exclusions
- Making proposals more professional or clearer

---

## The Goal of a Roofing Proposal

A strong proposal does three things:
1. Explains *what* is being done
2. Sets expectations clearly
3. Prevents misunderstandings later

A proposal is not a sales pitch.
It is a professional agreement preview.

---

## Scope: Be Clear, Not Clever

Good scope language is:
- Specific
- Observable
- Measurable

### Strong scope example
“Remove existing roofing materials down to the decking on all roof planes.”

### Weak scope example
“Replace roof as needed.”

If a homeowner can interpret the sentence multiple ways, rewrite it.

---

## Explaining Measurements to Homeowners

Homeowners do not think in squares, pitches, or planes.

Translate measurements into:
- Areas of work
- Complexity
- Why the job costs what it costs

Avoid technical overload.
Clarity builds trust more than precision.

---

## Exclusions: Protection, Not Negativity

Exclusions are not disclaimers — they are clarity tools.

### Common exclusion categories
- Hidden damage
- Structural issues
- Code upgrades not visible at inspection
- Weather delays
- Material availability

Phrase exclusions calmly and professionally.
Avoid defensive or legalistic language.

---

## What NOT to Promise

Avoid:
- Guaranteed timelines
- Insurance outcomes
- Hidden condition assumptions
- Statements of approval or compliance

If something depends on conditions outside your control, say so clearly.

---

## Tone Guidelines

Professional tone is:
- Confident
- Calm
- Factual
- Respectful

Avoid:
- Hype
- Pressure language
- Overconfidence
- Slang or jokes

A proposal should feel safe to sign.

---

## Mentor Guidance

A proposal should make the homeowner feel informed, not sold.
Clarity now prevents conflict later.
```

### references/insurance-narratives.md

```markdown
# Insurance Claim Narratives & Adjuster-Facing Language

## Purpose

Provide neutral, professional language for insurance-facing documentation.

Use this reference when the user asks about:
- Writing claim narratives
- Insurance summaries
- Damage descriptions
- Adjuster communication

---

## Core Principle: Be Factual

Insurance narratives should describe *what is observed*, not *what is assumed*.

Do not:
- Assign cause
- Predict coverage
- State approval or denial

Stick to measurable, observable facts.

---

## Structure of a Good Claim Narrative

1. Property identification
2. Observed roof conditions
3. Measurement summary
4. Noted damage indicators
5. Limitations or constraints

Keep it concise and orderly.

---

## Language to Prefer

Use phrases like:
- “Observed”
- “Measured”
- “Noted during inspection”
- “Consistent with visible conditions”

Avoid:
- “Caused by”
- “Resulted from”
- “Guaranteed”
- “Confirmed damage source”

---

## Measurement References

When referencing measurements:
- State what was measured
- Avoid interpretation
- Avoid financial conclusions

Example:
“Multiple roof planes with varying pitch were measured and documented.”

---

## Tone Rules

- Neutral
- Professional
- Non-accusatory
- Non-speculative

The narrative should read the same regardless of outcome.

---

## Common Mistakes

- Mixing sales language into claim language
- Over-explaining
- Making coverage assumptions
- Emotional wording

---

## Mentor Guidance

Insurance documentation is about credibility.
Precision and restraint carry more weight than volume.
```

### references/workflow-best-practices.md

```markdown
# Roofing Workflow Best Practices

## Purpose

Reduce rework, missed details, and inefficiencies across roofing jobs.

Use this reference when the user asks about:
- Best workflows
- Field vs office responsibilities
- Avoiding mistakes
- Job handoffs

---

## The Roofing Workflow (Canonical)

1. Lead intake
2. Initial inspection
3. Measurement capture
4. Review and verification
5. Proposal or report generation
6. Material ordering
7. Job execution

Problems arise when steps blur together.

---

## Field vs Office Responsibilities

### Field is best for:
- Visual confirmation
- Photo documentation
- Geometry validation
- Condition notes

### Office is best for:
- Review and sanity checks
- Proposal drafting
- Narrative refinement
- Final verification

Trying to do everything in one place increases error.

---

## Capture Now vs Capture Later

Capture immediately:
- Photos
- Geometry confirmations
- Obvious anomalies

Capture later:
- Narrative refinement
- Final formatting
- Business decisions

Memory fades. Documentation doesn’t.

---

## Handoff Checkpoints

Before handing work off:
- Measurements reviewed
- Assumptions noted
- Missing data flagged

Never assume the next person “will figure it out.”

---

## Failure Patterns

Most rework comes from:
- Rushed measurements
- Missing photos
- Unclear notes
- Assumed understanding

Slow is smooth. Smooth is fast.

---

## Mentor Guidance

Good workflows protect good people from bad days.
Consistency beats speed.
```

### references/kpi-interpretation.md

```markdown
# Roofing Metrics & KPI Interpretation

## Purpose

Turn performance metrics into actionable decisions.

Use this reference when the user asks about:
- Conversion rates
- Performance issues
- Team productivity
- Business improvement

---

## Metrics Are Signals, Not Verdicts

A number alone does not explain a problem.
Context matters.

Always ask:
- Compared to what?
- Over what time period?
- Under what conditions?

---

## Conversion Rates

Low conversion may indicate:
- Lead quality issues
- Proposal clarity problems
- Pricing mismatch
- Follow-up gaps

High conversion with low margins can still be unhealthy.

---

## Volume vs Quality

More jobs does not always mean better performance.
Watch for:
- Burnout
- Rework rates
- Customer complaints

Sustainable growth is the goal.

---

## Team Performance

Compare individuals carefully.
Account for:
- Job type
- Complexity
- Role differences

Numbers should inform coaching, not punishment.

---

## What to Improve First

Prioritize:
1. Measurement accuracy
2. Proposal clarity
3. Workflow consistency

Fix foundations before scaling volume.

---

## Mentor Guidance

Metrics guide decisions.
They do not replace judgment.
```



---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### _meta.json

```json
{
  "owner": "abrahamventura",
  "slug": "roofing-knowledge-mentor",
  "displayName": "Roofing Knowledge Mentor",
  "latest": {
    "version": "1.0.0",
    "publishedAt": 1770041890717,
    "commit": "https://github.com/clawdbot/skills/commit/f8d77cdd81aca5f7837eb1d0eb45a0f27f5872d3"
  },
  "history": []
}

```

### scripts/quick_validate.py

```python
#!/usr/bin/env python3
"""
quick_validate.py

Lightweight validator for a Claude Skill directory.

Checks:
- Required SKILL.md exists
- YAML frontmatter exists and contains ONLY: name, description
- name/description are non-empty strings
- Optional folder conventions (scripts/, references/, assets/)
- Warns for common anti-patterns (README.md, extra docs)

Usage:
  python3 scripts/quick_validate.py
Exit codes:
  0 = success
  1 = validation errors
"""

from __future__ import annotations

import os
import re
import sys
from pathlib import Path
from typing import Dict, List, Tuple


ALLOWED_FRONTMATTER_KEYS = {"name", "description"}
DISALLOWED_TOP_LEVEL_FILES = {
    "README.md",
    "INSTALLATION_GUIDE.md",
    "QUICK_REFERENCE.md",
    "CHANGELOG.md",
}


def eprint(msg: str) -> None:
    print(msg, file=sys.stderr)


def read_text(path: Path) -> str:
    try:
        return path.read_text(encoding="utf-8")
    except UnicodeDecodeError:
        # fall back, but warn
        return path.read_text(errors="replace")


def parse_frontmatter(skill_md: str) -> Tuple[Dict[str, str], List[str]]:
    """
    Extract YAML-like frontmatter between first two '---' lines.
    We intentionally parse a tiny subset:
      key: value
    This avoids pulling in external YAML dependencies.

    Returns: (data, errors)
    """
    errors: List[str] = []
    data: Dict[str, str] = {}

    # Must start with '---'
    if not skill_md.lstrip().startswith("---"):
        errors.append("SKILL.md must begin with YAML frontmatter starting with '---'.")
        return data, errors

    # Capture first frontmatter block
    m = re.match(r"\s*---\s*\n(.*?)\n---\s*\n", skill_md, flags=re.DOTALL)
    if not m:
        errors.append("SKILL.md frontmatter block is missing closing '---'.")
        return data, errors

    fm = m.group(1).strip()
    if not fm:
        errors.append("SKILL.md frontmatter is empty. It must include name and description.")
        return data, errors

    # Parse simple "key: value" lines (no nesting allowed)
    for idx, line in enumerate(fm.splitlines(), start=1):
        raw = line.strip()
        if not raw or raw.startswith("#"):
            continue

        if ":" not in raw:
            errors.append(f"Frontmatter line {idx} is not a valid 'key: value' pair: {line!r}")
            continue

        key, value = raw.split(":", 1)
        key = key.strip()
        value = value.strip()

        if not key:
            errors.append(f"Frontmatter line {idx} has an empty key.")
            continue

        # Remove optional surrounding quotes
        if (value.startswith('"') and value.endswith('"')) or (value.startswith("'") and value.endswith("'")):
            value = value[1:-1].strip()

        data[key] = value

    return data, errors


def validate_frontmatter(data: Dict[str, str]) -> List[str]:
    errors: List[str] = []

    missing = [k for k in ("name", "description") if k not in data]
    if missing:
        errors.append(f"Frontmatter missing required field(s): {', '.join(missing)}")

    extra = [k for k in data.keys() if k not in ALLOWED_FRONTMATTER_KEYS]
    if extra:
        errors.append(
            "Frontmatter contains unsupported field(s): "
            + ", ".join(extra)
            + ". Only 'name' and 'description' are allowed."
        )

    name = data.get("name", "").strip()
    desc = data.get("description", "").strip()

    if "name" in data and not name:
        errors.append("Frontmatter field 'name' must be a non-empty string.")
    if "description" in data and not desc:
        errors.append("Frontmatter field 'description' must be a non-empty string.")

    # Gentle quality warnings (not errors) are handled elsewhere
    return errors


def validate_skill_dir(root: Path) -> Tuple[List[str], List[str]]:
    """
    Returns (errors, warnings)
    """
    errors: List[str] = []
    warnings: List[str] = []

    if not root.exists():
        errors.append(f"Skill directory does not exist: {root}")
        return errors, warnings

    skill_md_path = root / "SKILL.md"
    if not skill_md_path.exists():
        errors.append("Missing required file: SKILL.md")
        return errors, warnings

    # Top-level clutter warnings
    for bad in DISALLOWED_TOP_LEVEL_FILES:
        if (root / bad).exists():
            warnings.append(f"Top-level file '{bad}' is discouraged for skills (remove it).")

    # Parse + validate frontmatter
    skill_md = read_text(skill_md_path)
    fm_data, fm_parse_errors = parse_frontmatter(skill_md)
    errors.extend(fm_parse_errors)
    if not fm_parse_errors:
        errors.extend(validate_frontmatter(fm_data))

    # Optional directories are fine, but if present, they should be directories
    for dirname in ("scripts", "references", "assets"):
        p = root / dirname
        if p.exists() and not p.is_dir():
            errors.append(f"'{dirname}' exists but is not a directory.")

    # Check reference depth: discourage nested reference folders beyond one level
    ref_dir = root / "references"
    if ref_dir.exists():
        for sub in ref_dir.rglob("*"):
            if sub.is_dir() and sub != ref_dir:
                # allow only one level deep (references/*.md). anything deeper warns
                rel_parts = sub.relative_to(ref_dir).parts
                if len(rel_parts) > 1:
                    warnings.append(
                        f"Deeply nested references folder found: references/{sub.relative_to(ref_dir)} "
                        "(prefer one level deep from SKILL.md)."
                    )

    # Warn if SKILL.md is huge (approx line count)
    line_count = skill_md.count("\n") + 1
    if line_count > 500:
        warnings.append(
            f"SKILL.md is {line_count} lines (>500). Consider moving details into references/."
        )

    # Small quality warning for description length
    if "description" in fm_data:
        if len(fm_data["description"].strip()) < 40:
            warnings.append("Frontmatter description seems short; include more trigger context.")

    return errors, warnings


def main() -> int:
    # Run from scripts/ by default; root is parent directory.
    here = Path(__file__).resolve()
    root = here.parent.parent

    errors, warnings = validate_skill_dir(root)

    if warnings:
        print("WARNINGS:")
        for w in warnings:
            print(f"  - {w}")
        print()

    if errors:
        eprint("VALIDATION FAILED:")
        for err in errors:
            eprint(f"  - {err}")
        return 1

    print("VALIDATION PASSED ✅")
    print(f"Skill directory: {root}")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())
```