# Pwaf Build Report

> How to write a build_report.md for any PWAF connector. Captures skill traceability, sufficiency assessment, and test error/fix log. Use after implementing any connector.

- Skill: `databricks-solutions/pwaf-build-report` (Agent Skill)
- Install (CLI): `npx skillmds@latest add databricks-solutions/pwaf-build-report`
- Raw SKILL.md: https://api.skillmd.com/api/skills/databricks-solutions/pwaf-build-report/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: databricks-solutions (https://skillmd.com/u/databricks-solutions)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/databricks-solutions/pwaf-build-report

---


<!-- skill-version: 1.0.0 -->

# Connector Build Report (PWAF)

Use this skill after implementing a PWAF connector to write the `build_report.md` traceability document. This document closes the feedback loop between connector implementations and the skills/rules that guided the agent.

---

## Purpose

`build_report.md` serves three purposes:
1. **Traceability** — which skills and rules were used to build this connector
2. **Sufficiency assessment** — did the skills contain enough information to build correctly on the first try, or were gaps encountered?
3. **Feedback loop** — the test error/fix log captures real failures so skills maintainers can improve the source material

---

## Required Sections

### 1. Header

```markdown
# Build Report: <connector-name>

**Date:** YYYY-MM-DD
**Auth types implemented:** PAT, OAuth M2M, OAuth U2M (custom app + token-env)
**Test result:** PASS / FAIL
```

### 2. Primary Skill

```markdown
## Primary Skill

| Field | Value |
|-------|-------|
| **Skill** | `skills/<connector-name>/SKILL.md` |
| **Version read** | Full file / First N lines |
| **Sufficient for implementation?** | YES / PARTIALLY / NO |
| **Gaps encountered** | <list any missing info, or "None"> |
```

### 3. Supporting Skills

List every skill file read beyond the primary skill.

```markdown
## Supporting Skills

| Skill | Purpose | Sufficient? |
|-------|---------|-------------|
| `skills/connector-structure/SKILL.md` | Config shape, connect() pattern | YES |
| `skills/u2m/SKILL.md` | PKCE flow, external-browser | YES |
| ... | ... | ... |
```

### 4. Rules Consulted

List every skill file read during implementation.

```markdown
## Skills Consulted

| Skill | Purpose | Gaps/Issues |
|-------|---------|-------------|
| `skills/<connector>/authentication.md` | Auth patterns for this SDK/driver | <or "None"> |
| `skills/connector-testing/env-isolation.md` | Test environment setup | None |
| ... | ... | ... |
```

### 5. External Resources

Any URLs, docs, or sources consulted outside the skills/rules.

```markdown
## External Resources

| Resource | Why Needed | Should be in skills? |
|----------|------------|----------------------|
| GitHub issue #NNN | Error not covered in skill | YES — add to troubleshooting |
| Official docs URL | Missing API detail | MAYBE |
| None | — | — |
```

### 6. PWAF Checklist

```markdown
## PWAF Checklist

| Item | Status | Notes |
|------|--------|-------|
| User-Agent set on every request | ✅ | Format: `Company_Product/1.0.0` |
| PAT auth implemented | ✅ / ❌ / N/A | |
| OAuth M2M implemented | ✅ / ❌ / N/A | |
| OAuth U2M (custom app) implemented | ✅ / ❌ / N/A | |
| OAuth U2M (token-env) implemented | ✅ / ❌ / N/A | |
| All auth types pass integration tests | ✅ / ❌ | |
| env -i isolation used in tests | ✅ / ❌ | |
| DATABRICKS_AUTH_TYPE NOT set in env | ✅ / ❌ | |
```

### 7. Sufficiency Assessment

```markdown
## Sufficiency Assessment

**Overall verdict:** SUFFICIENT / PARTIALLY SUFFICIENT / INSUFFICIENT

**Verdict rubric:**
- **SUFFICIENT**: Implementation succeeded without consulting anything outside the skills/rules. No test failures caused by missing skill information.
- **PARTIALLY SUFFICIENT**: Implementation succeeded but required consulting external resources or working around gaps. At least one test failure traceable to a skill gap.
- **INSUFFICIENT**: Could not complete implementation using skills/rules alone. Significant information missing.

**Key gaps (if any):**
- <Skill X doesn't cover Y — led to error Z>
- <Rule file uses inconsistent variable name — caused auth conflict>
```

### 8. Test Error / Fix Log

This is the most important section for skills maintainers. Record every test failure that was caused by incorrect or missing skill information.

```markdown
## Test Error / Fix Log

### Error 1: <short error description>

**Error message:**
```
<exact error text from terminal>
```

**Root cause:** <what was wrong — wrong skill info, missing info, env pollution, etc.>

**Fix applied:** <what change fixed it>

**Skill gap:** <which skill was wrong or missing — "skills/foo/authentication.md line 42 says X but the correct value is Y">

**Recommendation:** <what should be added/changed in the skill>

---

### Error 2: ...
```

**What counts as a skill gap vs infrastructure issue:**

| Category | Examples | Record in skill gap? |
|----------|----------|----------------------|
| Skill gap | Wrong value in code example, missing variable name, incorrect pom.xml config | YES |
| Environment issue | Port already in use, SSL error, missing env var | NO (unless skill should warn about it) |
| Infrastructure issue | Network timeout, workspace quota | NO |
| Test runner issue | Wrong flag passed to test script | NO |

If there were no errors, write: `No test failures — all auth types passed on first attempt.`

---

## Template

Copy this template for a new `build_report.md`:

```markdown
# Build Report: <connector-name>

**Date:** YYYY-MM-DD
**Auth types implemented:** PAT, OAuth M2M, OAuth U2M (custom app + token-env)
**Test result:** PASS

## Primary Skill

| Field | Value |
|-------|-------|
| **Skill** | `skills/<connector-name>/SKILL.md` |
| **Sufficient for implementation?** | YES |
| **Gaps encountered** | None |

## Supporting Skills

| Skill | Purpose | Sufficient? |
|-------|---------|-------------|
| `skills/connector-structure/SKILL.md` | Config/connect pattern | YES |
| `skills/u2m/SKILL.md` | PKCE and browser flows | YES |

## Skills Consulted

| Skill | Purpose | Gaps/Issues |
|-------|---------|-------------|
| `skills/<connector>/authentication.md` | Auth patterns | None |
| `skills/connector-testing/env-isolation.md` | Test isolation | None |

## External Resources

None

## PWAF Checklist

| Item | Status |
|------|--------|
| User-Agent set on every request | ✅ |
| PAT auth implemented | ✅ |
| OAuth M2M implemented | ✅ |
| OAuth U2M (custom app) implemented | ✅ |
| OAuth U2M (token-env) implemented | ✅ |
| All auth types pass integration tests | ✅ |
| env -i isolation used in tests | ✅ |
| DATABRICKS_AUTH_TYPE NOT set in env | ✅ |

## Sufficiency Assessment

**Overall verdict:** SUFFICIENT

## Test Error / Fix Log

No test failures — all auth types passed on first attempt.
```

---

## File Location

Place `build_report.md` in the connector's implementation directory:

```
connectors/<connector-name>/build_report.md
```

or at the connector project root if covering all connectors:

```
build_report.md
```