diff --git a/.cursor/rules/harbor_pilot_universal.mdc b/.cursor/rules/harbor_pilot_universal.mdc new file mode 100644 index 00000000..8f3c1ef8 --- /dev/null +++ b/.cursor/rules/harbor_pilot_universal.mdc @@ -0,0 +1,204 @@ +--- +alwaysApply: true +inherits: base_context.mdc +--- +```json +{ + "coaching_level": "standard", + "socratic_max_questions": 2, + "verbosity": "concise", + "timebox_minutes": 10, + "format_enforcement": "strict" +} +``` + +# Harbor Pilot — Universal Directive for Human-Facing Technical Guides + +**Author**: System/Shared +**Date**: 2025-08-21 (UTC) +**Status**: 🚢 ACTIVE — General ruleset extending *Base Context — Human Competence First* + +> **Alignment with Base Context** +> - **Purpose fit**: Prioritizes human competence and collaboration while delivering reproducible artifacts. +> - **Output Contract**: This directive **adds universal constraints** for any technical topic while **inheriting** the Base Context contract sections. +> - **Toggles honored**: Uses the same toggle semantics; defaults above can be overridden by the caller. + +--- + +## Objective +Produce a **developer-grade, reproducible guide** for any technical topic that onboards a competent practitioner **without meta narration** and **with evidence-backed steps**. + +## Scope & Constraints +- **One Markdown document** as the deliverable. +- Use **absolute dates** in **UTC** (e.g., `2025-08-21T14:22Z`) — avoid “today/yesterday”. +- Include at least **one diagram** (Mermaid preferred). Choose the most fitting type: + - `sequenceDiagram` (protocols/flows), `flowchart`, `stateDiagram`, `gantt` (timelines), or `classDiagram` (schemas). +- Provide runnable examples where applicable: + - **APIs**: `curl` + one client library (e.g., `httpx` for Python). + - **CLIs**: literal command blocks and expected output snippets. + - **Code**: minimal, self-contained samples (language appropriate). +- Cite **evidence** for *Works/Doesn’t* items (timestamps, filenames, line numbers, IDs/status codes, or logs). +- If something is unknown, output `TODO:` — **never invent**. + +## Required Sections (extends Base Output Contract) +Follow this exact order **after** the Base Contract’s **Objective → Result → Use/Run** headers: + +1. **Context & Scope** + - Problem statement, audience, in/out-of-scope bullets. +2. **Artifacts & Links** + - Repos/PRs, design docs, datasets/HARs/pcaps, scripts/tools, dashboards. +3. **Environment & Preconditions** + - OS/runtime, versions/build IDs, services/endpoints/URLs, credentials/auth mode (describe acquisition, do not expose secrets). +4. **Architecture / Process Overview** + - Short prose + **one diagram** selected from the list above. +5. **Interfaces & Contracts (choose one)** + - **API-based**: Endpoint table (*Step, Method, Path/URL, Auth, Key Headers/Params, Sample Req/Resp ref*). + - **Data/Files**: I/O contract table (*Source, Format, Schema/Columns, Size, Validation rules*). + - **Systems/Hardware**: Interfaces table (*Port/Bus, Protocol, Voltage/Timing, Constraints*). +6. **Repro: End-to-End Procedure** + - Minimal copy-paste steps with code/commands and **expected outputs**. +7. **What Works (with Evidence)** + - Each item: **Time (UTC)** • **Artifact/Req IDs** • **Status/Result** • **Where to verify**. +8. **What Doesn’t (Evidence & Hypotheses)** + - Each failure: locus (file/endpoint/module), evidence snippet; short hypothesis and **next probe**. +9. **Risks, Limits, Assumptions** + - SLOs/limits, rate/size caps, security boundaries (CORS/CSRF/ACLs), retries/backoff/idempotency patterns. +10. **Next Steps (Owner • Exit Criteria • Target Date)** + - Actionable, assigned, and time-bound. +11. **References** + - Canonical docs, specs, tickets, prior analyses. + +> **Competence Hooks (per Base Context; keep lightweight):** +> - *Why this works* (≤3 bullets) — core invariants or guarantees. +> - *Common pitfalls* (≤3 bullets) — the traps we saw in evidence. +> - *Next skill unlock* (1 line) — the next capability to implement/learn. +> - *Teach-back* (1 line) — prompt the reader to restate the flow/architecture. + +> **Collaboration Hooks (per Base Context):** +> - Name reviewers for **Interfaces & Contracts** and the **diagram**. +> - Short **sign-off checklist** before merging/publishing the guide. + +## Do / Don’t (Base-aligned) +- **Do** quantify progress only against a defined scope with acceptance criteria. +- **Do** include minimal sample payloads/headers or I/O schemas; redact sensitive values. +- **Do** keep commentary lean; if timeboxed, move depth to **Deferred for depth**. +- **Don’t** use marketing language or meta narration (“Perfect!”, “tool called”, “new chat”). +- **Don’t** include IDE-specific chatter or internal rules unrelated to the task. + +## Validation Checklist (self-check before returning) +- [ ] All Required Sections present and ordered. +- [ ] Diagram compiles (basic Mermaid syntax) and fits the problem. +- [ ] If API-based, **Auth** and **Key Headers/Params** are listed for each endpoint. +- [ ] Repro section includes commands/code **and expected outputs**. +- [ ] Every Works/Doesn’t item has **UTC timestamp**, **status/result**, and **verifiable evidence**. +- [ ] Next Steps include **Owner**, **Exit Criteria**, **Target Date**. +- [ ] Unknowns are `TODO:` — no fabrication. +- [ ] Base **Output Contract** sections satisfied (Objective/Result/Use/Run/Competence/Collaboration/Assumptions/References). + +## Universal Template (fill-in) +```markdown +# — Working Notes (As of YYYY-MM-DDTHH:MMZ) + +## Objective +<one line> + +## Result +<link to the produced guide file or say “this document”> + +## Use/Run +<how to apply/test and where to run samples> + +## Context & Scope +- Audience: <role(s)> +- In scope: <bullets> +- Out of scope: <bullets> + +## Artifacts & Links +- Repo/PR: <link> +- Data/Logs: <paths or links> +- Scripts/Tools: <paths> +- Dashboards: <links> + +## Environment & Preconditions +- OS/Runtime: <details> +- Versions/Builds: <list> +- Services/Endpoints: <list> +- Auth mode: <Bearer/Session/Keys + how acquired> + +## Architecture / Process Overview +<short prose> +```mermaid +<one suitable diagram: sequenceDiagram | flowchart | stateDiagram | gantt | classDiagram> +``` + +## Interfaces & Contracts +### If API-based +| Step | Method | Path/URL | Auth | Key Headers/Params | Sample | +|---|---|---|---|---|---| +| <…> | <…> | <…> | <…> | <…> | below | + +### If Data/Files +| Source | Format | Schema/Columns | Size | Validation | +|---|---|---|---|---| +| <…> | <…> | <…> | <…> | <…> | + +### If Systems/Hardware +| Interface | Protocol | Timing/Voltage | Constraints | Notes | +|---|---|---|---|---| +| <…> | <…> | <…> | <…> | <…> | + +## Repro: End-to-End Procedure +```bash +# commands / curl examples (redacted where necessary) +``` +```python +# minimal client library example (language appropriate) +``` +> Expected output: <snippet/checks> + +## What Works (Evidence) +- ✅ <short statement> + - **Time**: <YYYY-MM-DDTHH:MMZ> + - **Evidence**: file/line/log or request id/status + - **Verify at**: <where> + +## What Doesn’t (Evidence & Hypotheses) +- ❌ <short failure> at `<component/endpoint/file>` + - **Time**: <YYYY-MM-DDTHH:MMZ> + - **Evidence**: <snippet/id/status> + - **Hypothesis**: <short> + - **Next probe**: <short> + +## Risks, Limits, Assumptions +<bullets: limits, security boundaries, retries/backoff, idempotency, SLOs> + +## Next Steps +| Owner | Task | Exit Criteria | Target Date (UTC) | +|---|---|---|---| +| <name> | <action> | <measurable outcome> | <YYYY-MM-DD> | + +## References +<links/titles> + +## Competence Hooks +- *Why this works*: <≤3 bullets> +- *Common pitfalls*: <≤3 bullets> +- *Next skill unlock*: <1 line> +- *Teach-back*: <1 line> + +## Collaboration Hooks +- Reviewers: <names/roles> +- Sign-off checklist: <≤5 checks> + +## Assumptions & Limits +<bullets> + +## Deferred for depth +<park deeper material here to respect timeboxing> +``` + +--- + +**Notes for Implementers:** +- Respect Base *Do-Not* (no filler, no invented facts, no censorship). +- Prefer clarity over completeness when timeboxed; capture unknowns explicitly.