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