@nurix/etna 0.1.2 → 0.2.0

package/data/harnesses/code/skills/documentation/references/examples.md

@@ -0,0 +1,193 @@
+# Documentation Examples
+
+Good vs bad examples showing the key differences.
+
+---
+
+## Example 1: Function Documentation
+
+### ❌ Bad: Full Implementation
+
+```markdown
+### mergeData
+
+function mergeData(server, local, changes) {
+const result = {};
+const serverMap = new Map(server.map((i) => [i.id, i]));
+// ... 30 more lines
+return result;
+}
+```
+
+**Problems:** Will become obsolete, focuses on HOW not WHAT.
+
+### ✅ Good: Contract Only
+
+```markdown
+### `mergeData(serverData, localData, changes)`
+
+**Goal:** Merge server data with local changes
+**Input:**
+
+-   `serverData` (array) - Fresh from API
+-   `localData` (array) - Current state
+-   `changes` (object) - `{ added, updated, removed }`
+    **Output:** `{ merged: array, conflicts: array }`
+
+**Merge Rules:**
+
+-   Server wins for conflicts
+-   Local additions preserved
+-   Local removals marked as intent
+```
+
+---
+
+## Example 2: State Documentation
+
+### ❌ Bad: State Everywhere
+
+```markdown
+## Component State
+
+const [items, setItems] = useState([]);
+
+## Hook State
+
+{ data: items, isLoading: loading, error: null }
+
+## Redux State
+
+{ items: [], loading: false, error: null }
+```
+
+**Problems:** Documents transient state, repeats shapes.
+
+### ✅ Good: Persistence Points Only
+
+```markdown
+## State
+
+**Frontend (at persistence):**
+{
+"data": [],
+"changes": { "added": [], "updated": [], "removed": [] }
+// "cache": {} // UNUSED: Deprecated
+}
+
+**Storage:** localStorage `app_state`
+
+**Backend:**
+model Item {
+id String @id
+data Json
+}
+```
+
+---
+
+## Example 3: Changelog
+
+### ❌ Bad: Vague
+
+```markdown
+# 2025-01-05 - Updates
+
+## Changes
+
+-   Updated editor
+-   Fixed bugs
+-   Improved performance
+
+## Files
+
+-   Various files in src/
+```
+
+### ✅ Good: Function-Level Detail
+
+```markdown
+# 2025-01-05 - Version-Based Merge
+
+## Summary
+
+Replaced change-tracking merge with version-based conflict resolution.
+
+## Changes
+
+### Added
+
+-   `mergeAndDerive(server, local, versionsMatch, type)` in `src/utils/merge.js`
+    -   Purpose: Single-pass merge with change detection
+    -   Returns: `{ merged, changes }`
+
+### Modified
+
+-   `useDataSync()` in `src/hooks/useDataSync.js`
+    -   Changed: Now compares versions before merge
+
+### Removed
+
+-   `deriveChanges()` from `src/utils/derive.js`
+    -   Replaced by: Logic in `mergeAndDerive()`
+
+## Breaking Changes
+
+⚠️ **Merge behavior changed**
+
+-   Old: Local changes always preserved
+-   New: Local preserved only if versions match
+
+## Files Changed
+
+-   `src/hooks/useDataSync.js`
+-   `src/utils/merge.js`
+-   `src/utils/derive.js` (deleted)
+```
+
+---
+
+## Example 4: Data Flow
+
+### ❌ Bad: Prose Description
+
+```markdown
+When the page loads, the useAppInit hook calls the syncData function.
+This function first fetches data from the server using the API. Then
+it gets the local data from Redux. After that, it compares versions...
+```
+
+### ✅ Good: Diagram + Key Points
+
+```markdown
+## Data Flow
+
+┌─────────────────────────────────────────┐
+│ DATA SYNC │
+├─────────────────────────────────────────┤
+│ │
+│ ┌──────┐ ┌──────┐ ┌──────┐ │
+│ │Server│────▶│Merge │────▶│Redux │ │
+│ │ API │ │ │ │Store │ │
+│ └──────┘ └──────┘ └──────┘ │
+│ │ │
+│ ▼ │
+│ Version Check │
+│ │
+└─────────────────────────────────────────┘
+
+**Trigger:** `useAppInit()` on page load
+**Version Rule:** Match → local wins, Mismatch → server wins
+```
+
+---
+
+## Quick Comparison
+
+| Aspect     | Bad                  | Good                        |
+| ---------- | -------------------- | --------------------------- |
+| Code       | Full implementations | Signatures + contracts      |
+| State      | Every occurrence     | Persistence points only     |
+| Flows      | Prose paragraphs     | ASCII diagrams              |
+| Changelogs | "Updated X"          | Function names + migrations |
+| Length     | 100+ lines           | 20-40 lines                 |

package/data/harnesses/code/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 |