```json

{
  "coaching_level": "standard",
  "socratic_max_questions": 2,
  "verbosity": "concise",
  "timebox_minutes": 10,
  "format_enforcement": "strict"
}

```

# Harbor Pilot Universal — Technical Guide Standards

> **Agent role**: When creating technical guides, reference documents, or
> implementation plans, apply these universal directives to ensure consistent
> quality and structure.

## Purpose

- **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.

## Core Directive

Produce a **developer-grade, reproducible guide** for any technical topic
that onboards a competent practitioner **without meta narration** and **with
evidence-backed steps**.

## Required Elements

### 1. Time & Date Standards

- 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).

### 2. Evidence Requirements

- **Reproducible Steps**: Every claim must have copy-paste commands

- **Verifiable Outputs**: Include expected results, status codes, or
  error messages

- **Cite evidence** for *Works/Doesn't* items (timestamps, filenames,
  line numbers, IDs/status codes, or logs).

## Required Sections

Follow this exact order **after** the Base Contract's **Objective → Result
→ Use/Run** headers:

1. **Artifacts & Links** - Repos/PRs, design docs, datasets/HARs/pcaps,
   scripts/tools, dashboards.

2. **Environment & Preconditions** - OS/runtime, versions/build IDs,
   services/endpoints/URLs, credentials/auth mode.

3. **Architecture / Process Overview** - Short prose + **one diagram**
   selected from the list above.

4. **Interfaces & Contracts** - Choose one: API-based (endpoint table),
   Data/Files (I/O contract), or Systems/Hardware (interfaces).

5. **Repro: End-to-End Procedure** - Minimal copy-paste steps with
   code/commands and **expected outputs**.
6. **What Works (with Evidence)** - Each item: **Time (UTC)** •
   **Artifact/Req IDs** • **Status/Result** • **Where to verify**.
7. **What Doesn't (Evidence & Hypotheses)** - Each failure: locus,
   evidence snippet; short hypothesis and **next probe**.
8. **Risks, Limits, Assumptions** - SLOs/limits, rate/size caps,
   security boundaries, retries/backoff/idempotency patterns.
9. **Next Steps (Owner • Exit Criteria • Target Date)** - Actionable,
   assigned, and time-bound.

## Quality Standards

### Do

- **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**.

- **Do** use specific, actionable language that guides implementation.

### Don't

- **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.

- **Don't** assume reader knowledge; provide context for all technical
  decisions.

## Model Implementation Checklist

### Before Creating Technical Guides

- [ ] **Scope Definition**: Clearly define problem, audience, and scope
- [ ] **Evidence Collection**: Gather specific timestamps, file references, and logs
- [ ] **Diagram Planning**: Plan appropriate diagram type for the technical process
- [ ] **Template Selection**: Choose relevant sections from required sections list

### During Guide Creation

- [ ] **Evidence Integration**: Include UTC timestamps and verifiable evidence
- [ ] **Diagram Creation**: Create Mermaid diagram that illustrates the process
- [ ] **Repro Steps**: Write copy-paste ready commands with expected outputs
- [ ] **Section Completion**: Fill in all required sections completely

### After Guide Creation

- [ ] **Validation**: Run through the validation checklist below
- [ ] **Evidence Review**: Verify all claims have supporting evidence
- [ ] **Repro Testing**: Test reproduction steps to ensure they work
- [ ] **Peer Review**: Share with technical leads for feedback

## Validation Checklist

Before publishing, verify:

- [ ] **Diagram included** and properly formatted (Mermaid syntax valid)
- [ ] If API-based, **Auth** and **Key Headers/Params** are listed for
  each endpoint
- [ ] **Environment section** includes all required dependencies and
  versions
- [ ] Every Works/Doesn't item has **UTC timestamp**, **status/result**,
  and **verifiable evidence**
- [ ] **Repro steps** are copy-paste ready with expected outputs
- [ ] Base **Output Contract** sections satisfied
  (Objective/Result/Use/Run/Competence/Collaboration/Assumptions/References)

## Integration Points

### Base Context Integration

- Apply historical comment management rules (see

  `.cursor/rules/development/historical_comment_management.mdc`)

- Apply realistic time estimation rules (see

  `.cursor/rules/development/realistic_time_estimation.mdc`)

### Competence Hooks

- **Why this works**: Structured approach ensures completeness and
  reproducibility

- **Common pitfalls**: Skipping evidence requirements, vague language

- **Next skill unlock**: Practice creating Mermaid diagrams for different
  use cases

- **Teach-back**: Explain how you would validate this guide's
  reproducibility

### Collaboration Hooks

- **Reviewers**: Technical leads, subject matter experts

- **Stakeholders**: Development teams, DevOps, QA teams

---

**Status**: 🚢 ACTIVE — General ruleset extending *Base Context — Human
Competence First*

**Priority**: Critical
**Estimated Effort**: Ongoing reference
**Dependencies**: base_context.mdc
**Stakeholders**: All AI interactions, Development teams

## Example Diagram Template

```mermaid

<one suitable diagram: sequenceDiagram | flowchart | stateDiagram | gantt |
classDiagram>

```

**Note**: Replace the placeholder with an actual diagram that illustrates
the technical process, architecture, or workflow being documented.
