pwaf-build-report

name	pwaf-build-report
description	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.

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

# 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

## 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.

## 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.

## 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.

## 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

## 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

## 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.

## Test Error / Fix Log

### Error 1: <short error description>

**Error message:**

```

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

Fix applied:

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