| 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:
- Traceability — which skills and rules were used to build this connector
- Sufficiency assessment — did the skills contain enough information to build correctly on the first try, or were gaps encountered?
- 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
