@nurix/etna 0.18.22 → 0.18.24

package/data/harnesses/mobile/skills/documentation/references/style-guide.md

@@ -1,315 +0,0 @@
-# Documentation Style Guide
-
-Writing rules for clear, maintainable documentation.
-
----
-
-## Function Documentation
-
-### Signature Format
-
-```markdown
-### `functionName(param1, param2, options)`
-
-**Goal:** One-line purpose **Input:**
-
-- `param1` (type) - Description
-- `param2` (type, optional) - Description **Output:** `{ field1, field2 }` **Side Effects:** State updates, API calls, etc.
-```
-
-### Parameter Rules
-
-- Name + type + one-line purpose
-- Mark optional params with `(type, optional)`
-- Nest object properties:
-  ```markdown
-  - `options` (object) - Configuration
-    - `options.retry` (boolean) - Enable retries
-    - `options.timeout` (number) - Timeout in ms
-  ```
-
-### Return Values
-
-Always specify:
-
-- Type: `Array<Object>`, `boolean`, `{ merged, changes }`
-- Shape for objects/arrays
-- Meaning: "True if sync successful"
-
----
-
-## State Documentation
-
-### When to Document State
-
-✅ Do:
-
-- Redux persistence (localStorage, IndexedDB)
-- Database schemas
-- API request/response shapes
-
-❌ Don't:
-
-- Component-level state
-- Derived/computed state
-- Temporary UI state
-
-### Format
-
-````markdown
-**Frontend (at persistence):**
-
-```json
-{
-  "activeField": "value"
-  // "deprecated": null  // UNUSED: Remove in v3
-}
-```
-````
-
-**Storage:** localStorage key `state_key`
-
-**Backend:**
-
-```sql
-model Table {
-  id   String @id
-  data Json
-  // old String?  // UNUSED: Legacy
-}
-```
-
-````
-
-### Mark Unused Keys
-
-Always comment deprecated/unused fields:
-```json
-{
-  "active": [],
-  // "legacy": {}  // UNUSED: Migrated to newField
-}
-````
-
----
-
-## ASCII Diagrams
-
-### When to Use
-
-- Data flows
-- System architecture
-- Component interactions
-- Process flows
-
-### Pattern
-
-```
-┌─────────────────────────────────────────┐
-│              TITLE                       │
-├─────────────────────────────────────────┤
-│                                          │
-│   ┌──────┐     ┌──────┐     ┌──────┐   │
-│   │  A   │────▶│  B   │────▶│  C   │   │
-│   └──────┘     └──────┘     └──────┘   │
-│        │                          │     │
-│        ▼                          ▼     │
-│    Detail                     Detail    │
-│                                          │
-└─────────────────────────────────────────┘
-```
-
-### Characters
-
-- Boxes: `┌─┐│└┘├┤┬┴┼`
-- Arrows: `───▶` `◀───` `│▼` `│▲`
-- Width: ~70 chars max
-
-### UI Wireframes
-
-For screen layouts (not data flows), use these conventions:
-
-```
-**Route:** `path/:id`
-**Tab:** Tab Name
-
-┌────────────────────────────────────┐
-│ Title   [i]3                [Button]│
-│ [i]Label   [Tag1][Tag2][+Add]       │
-└────────────────────────────────────┘
-```
-
-- `[text]` = clickable button/badge
-- `[i]` = icon (followed by label or count)
-- `v` / `^` = expand/collapse indicator
-- Show each UI state (collapsed/expanded) as separate diagrams
-- Include Route/Tab context above wireframe
-
----
-
-## Code Examples
-
-### Rules
-
-- Under 15 lines
-- Show contracts, not implementations
-- Use pseudocode for algorithms
-
-✅ Good:
-
-```javascript
-// Critical: Balanced brace matching
-function extract(json) {
-  // Track brace depth
-  // Ignore braces inside strings
-  // Return complete objects only
-}
-```
-
-❌ Bad: Full 50-line implementation
-
----
-
-## Writing Style
-
-### Voice
-
-Use imperative/active:
-
-- ✅ "Fetches data from server"
-- ✅ "Returns array of objects"
-- ❌ "This function is used to fetch"
-- ❌ "An array is returned"
-
-### When Prose Adds Value
-
-Prose is valuable for context that contracts can't capture:
-
-| Use Prose For | Example |
-| --- | --- |
-| Section intros | "When the editor mounts, `useAppInit` is called with the `appId` from URL." |
-| Non-obvious behavior | "The hook always fetches fresh data. There is no caching or version checking." |
-| Design rationale | "Why parallel fetches? Each entity type is independent, reducing load time." |
-| Edge cases | "If created then deleted before save, it's removed from `added[]` without adding to `removed[]`." |
-| Current limitations | "This hook is not currently integrated into the main flow." |
-| Usage context | "Used to show 'Unsaved' badge, warn before navigation, enable save buttons." |
-
-### When to Avoid Prose
-
-- Describing WHAT code does (use signatures instead)
-- Step-by-step flows (use diagrams instead)
-- Structured comparisons (use tables instead)
-
-### Conciseness
-
-One line when possible:
-
-- ✅ "Merge server data with local changes using version-based conflict resolution"
-- ❌ "This function takes the data from the server and also takes the local data..."
-
-### Tables
-
-Use for structured info:
-
-```markdown
-| Parameter | Type   | Description    |
-| --------- | ------ | -------------- |
-| `data`    | object | Fresh from API |
-| `local`   | object | Current state  |
-```
-
----
-
-## The Two Natures — Tense & History
-
-Every document is a **truth document** (states current absolutes, updated in place) or a **record** (dated account of activity, frozen or append-only) — see `SKILL.md` § The Two Natures. The tense rules follow directly:
-
-**Truth documents describe the present, not the past.** Everything outside `docs/history/` states what the system _is_ and how it works _today_. It must not narrate how it got there. The journey — the dates, the migrations — lives **only** in records (`docs/history/`: changelog, plans, migrations). Two sanctioned exceptions: `docs/memory/` is the agent's own dated ledger, and an AD's **Decision Changelog** tail carries that decision's dated revision history (the AD body stays current-truth-only — head is truth, tail is provenance).
-
-**Records are never edited to match the present.** A frozen plan stays wrong-in-hindsight; a changelog entry describes what shipped as it shipped. A scope change gets a new dated record that links back.
-
-Strip this language from truth documents:
-
-| ❌ Historical narration (belongs in a record) | ✅ Present-tense fact (belongs in the truth doc) |
-| --- | --- |
-| "Folded in from the `NuStack-X` repo (2026-06-12)." | "Vendor-connector catalogue; one subpath per vendor." |
-| "Built 2026-06-14; shipped + verified 2026-06-13." | "`agentSessionWorkflow` runs an outer turn loop over `runAgentLoop`." |
-| "The legacy worker was deleted in the 2026-06-14 fold." | "One worker interprets `WorkflowDefinition`." |
-| "ex-`@nurix/mcp-runtime`, M9 Phase C; was X, now Y." | "MCP client runtime, wired into `agentTriggerWorkflow`." |
-| "Read first: `docs/history/plans/2026-…-fold.md`" (routing) | "Read first: `docs/architecture/<current-truth-doc>.md`" |
-
-Rules:
-
-- **No dates in truth documents** for when something shipped, was verified, folded, or was removed. A bare status marker (`✅ shipped`, `⏳ pending`) is fine; the _date_ it shipped is not.
-- **Cite the AD for the _why_, never the _when_.** `Provenance: AD-002` is good (it points to the decision rationale). "Decided in AD-002 and shipped 2026-06-13" is not.
-- **Routing/index docs point only to truth documents.** A row whose only "read first" target is a historical plan or changelog is a redirect-for-history — repoint it to the current truth doc, or drop the row.
-- **When a doc changes because the system changed, the change-story goes in `docs/history/` (a changelog entry), and the truth document simply becomes correct in present tense.** Never leave the diff narrated in place.
-- **A decision that moves is an edit, not a new document.** Rewrite the AD's affected sections to the new truth and append the revision to its Decision Changelog — never mint a parallel doc and never leave the old choice narrated in the body.
-
----
-
-## Structure
-
-### Headers
-
-```markdown
-# Document Title (H1 - once)
-
-## Major Section (H2)
-
-### Subsection (H3)
-
-#### Detail (H4 - sparingly)
-```
-
-**Headings are retrieval keys.** Search and agents retrieve sections out of context, and a bare `## State` reads identically across every feature doc. In long docs, qualify generic headings with the feature name — `## State — invoice-pdf`, `### Merge rules — data sync` — so a section stands alone when retrieved. Short docs whose H1 disambiguates can keep bare headings.
-
-### Standard Layout
-
-```markdown
-# [Title]
-
-**Goal:** One-line purpose
-
-## Architecture
-
-[Diagram + explanation]
-
-## Key Functions
-
-[Signatures and contracts]
-
-## State
-
-[Persistence shapes]
-
-## Files
-
-[Source file list]
-```
-
-### File References
-
-Always end with:
-
-```markdown
-## Files
-
-- `src/path/main.js` - Core logic
-- `src/path/hooks.js` - React hooks
-```
-
----
-
-## Summary
-
-| Aspect     | Rule                            |
-| ---------- | ------------------------------- |
-| Functions  | Always include signatures       |
-| Parameters | Type + purpose                  |
-| Returns    | Type + shape                    |
-| State      | Persistence points only         |
-| Diagrams   | ASCII for all flows             |
-| Code       | Under 15 lines, contracts only  |
-| Voice      | Imperative/active               |
-| Length     | Concise, one line when possible |