> ## Documentation Index
> Fetch the complete documentation index at: https://meganharrisonconsulting.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# procore-docs-rag

> >

This page is generated from the actual `SKILL.md` file on disk.

## Metadata

| Field               | Value                                                                               |
| ------------------- | ----------------------------------------------------------------------------------- |
| Source group        | Workspace Skills                                                                    |
| Source root         | `/Users/meganharrison/Documents/alleato-pm/.codex/skills`                           |
| Relative skill path | `procore-docs-rag/SKILL.md`                                                         |
| Actual file         | `/Users/meganharrison/Documents/alleato-pm/.codex/skills/procore-docs-rag/SKILL.md` |
| Description         | >                                                                                   |
| Docs overview       | [Workspace Skills](/skills/workspace-skills)                                        |

## Why this exists

Use this page when you want to review the real instructions behind a skill
without leaving the docs site. The content below is copied from the actual
`SKILL.md` file, not rewritten by hand.

## Raw SKILL.md

````md theme={null}
---
name: procore-docs-rag
description: >
  Query the Procore support article embeddings stored in Supabase before planning
  or implementing any feature, fix, or behavior tied to Procore functionality.
  Use when: building a feature that mirrors Procore, fixing behavior where the
  correct Procore behavior is unclear, verifying statuses/workflows/field names,
  or any time you would otherwise guess how Procore works.
argument-hint: "<your question about Procore>"
---

# Procore Docs RAG — Ground Truth Lookup (Three-Tier)

**Purpose:** Find authoritative Procore behavior before writing a single line of code.
This skill now has three escalating tiers so you never hit a dead end.

| Tier | Source | Best for |
|------|--------|----------|
| 1 | Supabase RAG (560 embedded articles) | Workflows, statuses, business rules |
| 2 | Deep Crawl Manifests (live DOM captures) | Exact field names, columns, tabs, options |
| 3 | Procore Support Site (WebFetch) | Full article text when embeddings give partial chunks |

Run all three tiers for complex features. They answer different questions.

---

## WHEN TO USE THIS SKILL

Use this **before** any of the following:

- Building a page/form/workflow that mirrors a Procore tool
- Fixing a bug where the expected behavior is ambiguous
- Planning statuses, transitions, field names, or validation rules
- Deciding whether a field is required, optional, or conditionally required
- Implementing a financial calculation (markup %, tax %, budget impact)
- Deciding what columns belong in a list view or what tabs belong on a detail view
- Any time you're about to guess how Procore does something

**Do not skip this step and rely on training data.** Procore has specific, non-obvious
behaviors (e.g., how PCOs relate to CCOs, what triggers a budget impact, which fields
are read-only after approval) that training data regularly gets wrong.

---

## TIER 1 — Supabase RAG

Run from the **project root**:

```bash
node scripts/procore-docs-query.js "your question here"
node scripts/procore-docs-query.js "invoicing workflow" 12   # optional topK (default 8)
```

### Score thresholds

| Score | Action |
|-------|--------|
| ≥ 80% | **Authoritative.** Use directly. |
| 60–79% | Good. Use with the article title as context. |
| 40–59% | Partial. Supplement with Tier 2 or 3. |
| < 40% | Low signal. Rephrase query, then escalate. |

### When RAG results are weak

1. **Rephrase** — use Procore's own terminology (e.g., "PCO" not "change request")
2. **Broaden** — remove specifics ("budget" instead of "budget forecast to complete column")
3. **Use category terms** — "prime contract", "commitment", "direct cost", "change event"
4. After two attempts with no strong results → proceed to Tier 2 and/or Tier 3

### Example queries

```bash
node scripts/procore-docs-query.js "what statuses does a change order go through"
node scripts/procore-docs-query.js "how does forecast to complete work in the budget"
node scripts/procore-docs-query.js "what fields are required when creating a commitment"
node scripts/procore-docs-query.js "how do potential change orders relate to change events"
node scripts/procore-docs-query.js "what happens to budget when a prime contract change order is approved"
node scripts/procore-docs-query.js "what is the difference between direct costs and commitments"
```

### What to do with results

1. **Read the content chunks**, not just the titles
2. **Note exact field names, status names, and workflow steps** — use Procore's exact
   wording in forms, labels, and status badges
3. **Note which fields are required** — match Procore's validation rules
4. **Note workflow transitions** — statuses have specific allowed transitions in Procore
5. **Save the source URLs** — you'll use them in Tier 3 if you need the full article

---

## TIER 2 — Deep Crawl Manifests (Live DOM Captures)

These files were captured by a Playwright script that literally scraped the live Procore
UI and saved the raw DOM + structured field extraction. They are authoritative for
**structural questions**: what columns, fields, tabs, and options does Procore actually
show?

### Manifest location

```
.claude/procore-manifests/{tool-slug}/
  manifest.json          ← structured field/column/tab extraction
  dom/list.html          ← raw HTML of the list view (100% trustworthy)
  dom/create-form.html   ← raw HTML of the create form
  dom/detail-*.html      ← raw HTML of detail states
  screenshots/           ← PNG screenshots (visual reference only)
```

### Available tool slugs

```
budget          change-events   change-orders   commitments
daily-log       direct-costs    directory       documents
drawings        invoicing       photos          prime-contracts
punch-list      rfis            specifications  submittals
```

### How to read a manifest

```bash
# Read the structured manifest
Read .claude/procore-manifests/{tool-slug}/manifest.json

# Read raw DOM for a specific state (list, create-form, detail)
Read .claude/procore-manifests/{tool-slug}/dom/list.html
```

### What to trust in manifest.json

**TRUSTWORTHY — extracted directly from DOM elements:**
- `states[].columns[].label` — exact column headers in the list view
- `states[].formSections[].fields[].label` — exact field labels
- `states[].formSections[].fields[].type` — field type (text, select, date, etc.)
- `states[].formSections[].fields[].required` — required flag
- `states[].formSections[].fields[].options[]` — dropdown option values
- `states[].formSections[].fields[].placeholder` — placeholder text
- `states[].tabs[]` — tab names on detail views
- `states[].filters[]` — filter options
- `states[].rowActions[]` — row-level action buttons
- `states[].headerFields[]` — header/summary fields

**USE WITH CAUTION — may contain summarized or inferred content:**
- `states[].description` — written by the crawl script, not Procore
- `states[]._capture_note` — may be AI-generated annotation
- Any field that reads like a prose sentence rather than a UI label

**If in doubt, cross-reference with the raw DOM HTML** — the HTML files contain only
what was literally rendered on the page. There is zero hallucination risk in raw HTML.

### Example: checking what columns the Change Orders list shows

```bash
# Read the manifest and look at states.list.columns
Read .claude/procore-manifests/change-orders/manifest.json
```

### Example: checking what fields are on the Commitment create form

```bash
# Read the manifest for form sections and fields
Read .claude/procore-manifests/commitments/manifest.json
# If manifest fields look incomplete, read the raw DOM
Read .claude/procore-manifests/commitments/dom/create-form.html
```

---

## TIER 3 — Procore Support Site (WebFetch)

Use WebFetch to get the full content of Procore support articles when:
- Tier 1 returned a URL but only a 500-char chunk (you need the full article)
- You need to verify a specific workflow step that the chunk cut off
- Tier 1 and Tier 2 together don't answer the question

### Option A: Fetch a full article from a RAG result URL

RAG results include a `URL` field pointing to the official Procore support article.
Fetch it directly:

```
WebFetch https://support.procore.com/faq/...     (URL from RAG result)
```

### Option B: Search the Procore documentation site

The Procore v2 support site is at `https://v2.support.procore.com/`. If you need to
discover articles the RAG doesn't surface, fetch the site and follow relevant links:

```
WebFetch https://v2.support.procore.com/
```

You can also construct likely article URLs based on the tool name, e.g.:
```
WebFetch https://v2.support.procore.com/hc/en-us/categories/change-orders
```

### What to trust from WebFetch

Everything fetched from `v2.support.procore.com` or `support.procore.com` is
**official Procore documentation** — treat it as authoritative. Read it the same
way you would the RAG chunks: note exact field names, statuses, and workflow steps.

---

## COMBINING ALL THREE TIERS

For complex features, run all tiers:

```bash
# Example: implementing the Invoicing feature

# Tier 1 — business rules and workflows
node scripts/procore-docs-query.js "invoice statuses and approval workflow"
node scripts/procore-docs-query.js "what fields are required on an invoice"
node scripts/procore-docs-query.js "how does invoicing relate to commitments"

# Tier 2 — exact UI structure from live Procore
Read .claude/procore-manifests/invoicing/manifest.json
Read .claude/procore-manifests/invoicing/dom/create-form.html   # if field detail needed

# Tier 3 — if a specific workflow step is still unclear
WebFetch https://support.procore.com/faq/...   # URL from Tier 1 results
```

---

## QUICK REFERENCE

| What | Detail |
|------|--------|
| RAG script | `scripts/procore-docs-query.js` (run from project root) |
| RAG data source | Supabase `search_support_articles` RPC |
| Embedding model | `text-embedding-3-large` (3072 dims) |
| Articles indexed | 560 Procore support pages |
| Manifest base path | `.claude/procore-manifests/` |
| Manifest tools | budget, change-events, change-orders, commitments, daily-log, direct-costs, directory, documents, drawings, invoicing, photos, prime-contracts, punch-list, rfis, specifications, submittals |
| Support site | `https://v2.support.procore.com/` |
| Env vars needed | `NEXT_PUBLIC_SUPABASE_URL`, `SUPABASE_SERVICE_ROLE_KEY`, `AI_GATEWAY_API_KEY` or `OPENAI_API_KEY` (all in `frontend/.env`) |
| Production API | `POST /api/procore-docs/ask` (requires session auth — use script for CLI) |
| Chat UI | `/procore-docs` page in the app |

````