// 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.
Build PWAF-compliant ISV integrations with Databricks: OAuth, telemetry (User-Agent), Unity Catalog, JDBC, SDK, SQL drivers, REST API, Databricks Connect.
PWAF-compliant Python SQL Connector (databricks-sql-connector): PAT, OAuth M2M, OAuth U2M (custom OAuth app PKCE + token-env), credentials_provider patterns, error handling, retry logic. Use when building Python integrations that run SQL queries via a Databricks SQL warehouse.
Add a Databricks connector to an existing project that has no Databricks integration. Use when your product already exists and you want to add Databricks as a new data source or backend.
How to structure a Databricks connector (REST or Python SDK): config, connect, operations, validation. Use when designing or building a new connector.
How to build and use a PWAF connector test runner (tests/run_all_tests.sh). Covers env isolation, auth types, single connector or single auth mode, parallel execution, browser tests, and report generation.
PWAF-compliant Databricks Connect (Python): PAT, OAuth M2M, OAuth U2M; serverless and classic compute. Use when building or testing Spark-over-Connect integrations.
| 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. |
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.
build_report.md serves three purposes:
# Build Report: <connector-name>
**Date:** YYYY-MM-DD
**Auth types implemented:** PAT, OAuth M2M, OAuth U2M (custom app + token-env)
**Test result:** PASS / FAIL
## 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"> |
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 |
| ... | ... | ... |
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 |
| ... | ... | ... |
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 | — | — |
## 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 | ✅ / ❌ | |
## 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>
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>
**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.
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