@nurix/etna 0.15.7 → 0.16.0

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

@@ -0,0 +1,288 @@
+# 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  |
+```
+
+---
+
+## Structure
+
+### Headers
+
+```markdown
+# Document Title (H1 - once)
+
+## Major Section (H2)
+
+### Subsection (H3)
+
+#### Detail (H4 - sparingly)
+```
+
+### 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 |