crowd-funder-for-time-pwa/.cursor/rules/harbor_pilot_universal.mdc

---
alwaysApply: false
---
```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:<missing>` — **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:<missing>` — no fabrication.  
- [ ] Base **Output Contract** sections satisfied (Objective/Result/Use/Run/Competence/Collaboration/Assumptions/References).

## Universal Template (fill-in)
```markdown
# <Title> — 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.
- Apply historical comment management rules (see `.cursor/rules/historical_comment_management.mdc`)
- Apply realistic time estimation rules (see `.cursor/rules/realistic_time_estimation.mdc`)
- Apply Playwright test investigation rules (see `.cursor/rules/playwright_test_investigation.mdc`)