mindforge-cc 10.0.2 → 10.7.0

package/.mindforge/skills/react-performance/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: react-performance
+version: 1.0.0
+min_mindforge_version: 10.0.6
+status: stable
+triggers: react performance, React.memo, useMemo pattern, useCallback pattern, react code splitting, react lazy loading, virtualization, bundle analysis, react profiler, render optimization, unnecessary re-render, react bundle size
+compose: performance
+---
+
+# Skill — React Performance
+
+## When this skill activates
+Any task involving React application performance: reducing unnecessary re-renders,
+optimizing bundle size, implementing code splitting, virtualizing long lists,
+profiling component render times, or improving Core Web Vitals in React apps.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. **Identify the performance problem with measurement.** Do not guess.
+   - Use React DevTools Profiler to record interactions and identify slow renders.
+   - Use the browser Performance tab to measure paint times and long tasks.
+   - Use `webpack-bundle-analyzer` or `@next/bundle-analyzer` to identify large chunks.
+2. Determine the category of problem:
+   - Unnecessary re-renders (component renders without visual change)
+   - Large bundle size (initial JS payload too big)
+   - Long lists without virtualization (DOM thrashing)
+   - Expensive computations on every render
+   - Layout thrashing (forced synchronous reflows)
+3. Set a measurable target before optimizing:
+   - LCP target (e.g., < 2.5s)
+   - Bundle size budget (e.g., initial JS < 200KB gzipped)
+   - Interaction latency (e.g., click-to-render < 100ms)
+
+### During implementation
+
+#### Identifying Re-renders
+- Install `@welldone-software/why-did-you-render` in development:
+  ```typescript
+  // wdyr.ts (import before React)
+  import React from "react";
+  if (process.env.NODE_ENV === "development") {
+    const whyDidYouRender = require("@welldone-software/why-did-you-render");
+    whyDidYouRender(React, { trackAllPureComponents: true });
+  }
+  ```
+- Use React DevTools Profiler "Highlight updates" to visually see which components re-render.
+- A re-render is wasteful ONLY if:
+  1. The component's output is identical to the previous render, AND
+  2. The render takes meaningful time (> 1ms measured in Profiler).
+
+#### React.memo
+- **When to use**: Component receives the same props frequently AND its render is expensive (> 5ms).
+- **When NOT to use**: Simple components (< 1ms render), components that always receive new props.
+- Implementation pattern:
+  ```typescript
+  const ExpensiveList = React.memo(function ExpensiveList({ items, onSelect }: Props) {
+    // expensive render logic
+    return <ul>{items.map(item => <ListItem key={item.id} item={item} onSelect={onSelect} />)}</ul>;
+  });
+  ```
+- Custom comparison for complex props:
+  ```typescript
+  const MemoizedChart = React.memo(ChartComponent, (prev, next) => {
+    return prev.data.length === next.data.length
+      && prev.data[0]?.id === next.data[0]?.id;
+  });
+  ```
+
+#### useMemo and useCallback
+- **Rule**: Do NOT add these by default. Add them ONLY when profiling shows a problem.
+- **useMemo** — use when:
+  - Computing derived data that is expensive (> 1ms) on every render
+  - Passing a computed object/array to a memoized child (reference stability)
+  ```typescript
+  const sortedItems = useMemo(
+    () => items.toSorted((a, b) => a.name.localeCompare(b.name)),
+    [items]
+  );
+  ```
+- **useCallback** — use when:
+  - Passing a callback to a memoized child component
+  - The callback is used as a dependency in a child's useEffect
+  ```typescript
+  const handleSelect = useCallback((id: string) => {
+    setSelected(id);
+  }, []);
+  ```
+- **Never use for**: Simple event handlers on non-memoized elements, values that change every render anyway.
+
+#### Code Splitting
+- Split at the route level (every page is a separate chunk):
+  ```typescript
+  const Dashboard = lazy(() => import("./pages/Dashboard"));
+  const Settings = lazy(() => import("./pages/Settings"));
+
+  function App() {
+    return (
+      <Suspense fallback={<PageSkeleton />}>
+        <Routes>
+          <Route path="/dashboard" element={<Dashboard />} />
+          <Route path="/settings" element={<Settings />} />
+        </Routes>
+      </Suspense>
+    );
+  }
+  ```
+- Split heavy libraries used in specific features:
+  ```typescript
+  const ChartModule = lazy(() => import("./components/ChartModule"));
+  // Only loaded when user navigates to analytics
+  ```
+- Use named webpack chunks for debugging: `import(/* webpackChunkName: "chart" */ "./Chart")`.
+- Prefetch likely-next routes on hover/focus:
+  ```typescript
+  const prefetchDashboard = () => import("./pages/Dashboard");
+  <Link onMouseEnter={prefetchDashboard} to="/dashboard">Dashboard</Link>
+  ```
+
+#### Virtualization (Long Lists)
+- Use virtualization when rendering > 50 items in a scrollable container.
+- Libraries: `@tanstack/react-virtual` (recommended), `react-window`, `react-virtuoso`.
+- Implementation pattern:
+  ```typescript
+  import { useVirtualizer } from "@tanstack/react-virtual";
+
+  function VirtualList({ items }: { items: Item[] }) {
+    const parentRef = useRef<HTMLDivElement>(null);
+    const virtualizer = useVirtualizer({
+      count: items.length,
+      getScrollElement: () => parentRef.current,
+      estimateSize: () => 48, // estimated row height in px
+      overscan: 5, // render 5 extra items above/below viewport
+    });
+
+    return (
+      <div ref={parentRef} style={{ height: "600px", overflow: "auto" }}>
+        <div style={{ height: `${virtualizer.getTotalSize()}px`, position: "relative" }}>
+          {virtualizer.getVirtualItems().map(virtualRow => (
+            <div
+              key={virtualRow.key}
+              style={{
+                position: "absolute",
+                top: 0,
+                transform: `translateY(${virtualRow.start}px)`,
+                height: `${virtualRow.size}px`,
+                width: "100%",
+              }}
+            >
+              <ListRow item={items[virtualRow.index]} />
+            </div>
+          ))}
+        </div>
+      </div>
+    );
+  }
+  ```
+- For grids, use the grid virtualizer variant.
+- Always provide `estimateSize` close to actual size to avoid layout jumps.
+
+#### Bundle Analysis
+- Generate and inspect the bundle:
+  ```bash
+  # Next.js
+  ANALYZE=true next build
+
+  # Vite
+  npx vite-bundle-visualizer
+
+  # Webpack
+  npx webpack --profile --json > stats.json
+  npx webpack-bundle-analyzer stats.json
+  ```
+- Common wins:
+  - Replace `moment` with `date-fns` or `dayjs` (save ~200KB).
+  - Replace `lodash` with individual imports: `import groupBy from "lodash/groupBy"`.
+  - Use dynamic import for heavy deps used in one feature (chart libs, PDF generators).
+  - Ensure tree-shaking: use ESM imports, check `sideEffects` in package.json.
+  - Remove unused dependencies: `npx depcheck`.
+
+#### Image Optimization
+- Use `next/image` (Next.js) or manual `<img loading="lazy" decoding="async">`.
+- Serve WebP/AVIF with `<picture>` fallback for older browsers.
+- Always specify `width` and `height` to prevent CLS.
+- Use responsive `srcset` for different viewport sizes.
+- Lazy load images below the fold; eager load the LCP image.
+
+#### State Management Performance
+- Colocate state: keep state as close to where it is used as possible.
+- Split context providers: one large context triggers re-renders on every consumer
+  for any state change. Split into focused providers.
+- Use selector patterns (`useSelector`, Zustand selectors) to subscribe to slices:
+  ```typescript
+  // Zustand: only re-renders when count changes
+  const count = useStore(state => state.count);
+  ```
+- Avoid putting frequently-changing values (mouse position, scroll offset) in React state.
+  Use refs or external stores.
+
+### After implementation
+1. Re-profile with React DevTools Profiler and compare flamegraphs.
+2. Run Lighthouse and compare scores (LCP, INP, CLS, Total Blocking Time).
+3. Verify bundle sizes with analyzer: confirm the target budget is met.
+4. Test on a throttled device (Chrome DevTools: 4x CPU slowdown, Slow 3G) to validate
+   the optimization matters in realistic conditions.
+5. Ensure no visual regressions: the UI must look and behave identically.
+
+## React performance anti-patterns to flag
+
+- `useMemo`/`useCallback` on every single function (adds overhead without benefit).
+- Inline object/array literals as props to memoized components (defeats memo).
+- Storing derived state that could be computed from existing state/props.
+- Re-creating context providers on every render (move value computation to useMemo).
+- Using `index` as key in lists that reorder (causes incorrect reconciliation).
+- Fetching data inside components without caching (use SWR, React Query, or similar).
+- Rendering 1000+ DOM nodes without virtualization.
+
+## Self-check before task completion
+
+Before marking a task done when this skill was active:
+
+- [ ] Performance problem was identified with profiling tools (not guessed).
+- [ ] Measurable improvement demonstrated (before/after numbers).
+- [ ] No unnecessary memoization added (each memo justified by measurement).
+- [ ] Bundle size budget verified with analyzer.
+- [ ] No visual or functional regressions introduced.
+- [ ] Optimizations tested on throttled device conditions.
+- [ ] Core Web Vitals (LCP, INP, CLS) meet targets.
+- [ ] Code splitting applied at route level minimum.

package/.mindforge/skills/real-time-analytics/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: real-time-analytics
+version: 1.0.0
+min_mindforge_version: 10.6.0
+status: stable
+triggers: real-time analytics architecture, OLAP cube design, materialized view strategy, pre-aggregation pipeline, sub-second query optimization, real-time dashboard backend, clickhouse architecture, druid pinot design, real-time metric computation, live analytics, streaming analytics, real-time aggregation
+---
+
+# Skill — Real-Time Analytics
+
+## When this skill activates
+This skill activates when building sub-second query systems for analytical workloads, implementing real-time dashboards, or designing OLAP architectures. Use when users need live insights rather than batch-refreshed reports.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. Profile query patterns to identify: aggregation dimensions, filter selectivity, time ranges, and concurrency requirements for index and materialization strategy
+2. Select appropriate OLAP engine: ClickHouse (fast scans, columnar), Druid (streaming ingestion, roll-ups), Pinot (low-latency queries), Redshift (AWS ecosystem)
+3. Design pre-aggregation strategy: which dimensions to roll up, granularity levels (minute/hour/day), and cardinality explosion prevention
+4. Calculate data volume and query throughput requirements: events/sec, retention period, query concurrency, and acceptable latency (p95/p99)
+
+### During implementation
+- Implement streaming ingestion pipeline: Kafka → transformation → OLAP store with exactly-once semantics and backpressure handling
+- Design table schema optimized for query patterns: sorting keys matching filters, partition keys for time pruning, materialized columns for computed fields
+- Create pre-aggregation jobs for common metrics: tumbling windows for counts/sums, HyperLogLog for distinct counts, quantile sketches for percentiles
+- Build materialized views for expensive joins and aggregations: incrementally updated, proper indexing, and staleness monitoring
+- Implement query optimization: partition pruning, secondary indexes, caching layer (Redis), and query result memoization
+- Design data retention policies: hot tier (recent, full granularity), warm tier (older, partial roll-up), cold tier (archived, summarized)
+- Create query routing layer: directing simple queries to pre-aggregations, complex queries to raw data with circuit breakers for expensive operations
+
+### After implementation
+- Build monitoring for ingestion pipeline: lag, throughput, error rates, and duplicate detection with alerting on anomalies
+- Create query performance dashboards: latency percentiles, query volume, cache hit rates, expensive queries, and optimization opportunities
+- Generate cost analysis reports: storage by tier, compute costs, query costs, and optimization recommendations (better indexes, more pre-aggs)
+- Document query best practices: efficient filtering, avoiding full scans, using pre-aggregations, and when to use caching
+
+## Self-check before task completion
+- [ ] Query latency meets SLA (typically p95 <1s, p99 <3s) for common dashboard queries under expected concurrency
+- [ ] Pre-aggregation strategy covers 80%+ of query patterns with automated refresh and staleness monitoring
+- [ ] Ingestion pipeline handles peak load with <1 minute lag and proper backpressure to prevent data loss
+- [ ] Data retention policy implemented with automated tiering and archival to optimize costs
+- [ ] Query optimization tested with partition pruning verified and slow query identification for further tuning

package/.mindforge/skills/real-time-sync/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: real-time-sync
+version: 1.0.0
+min_mindforge_version: 10.0.9
+status: stable
+triggers: real-time sync, conflict resolution, CRDT, operational transform, offline first, sync protocol, optimistic replication, last write wins, conflict merge strategy, eventual sync, sync engine, collaborative editing
+---
+
+# Skill — Real-Time Sync
+
+## When this skill activates
+Any task involving real-time synchronization, conflict resolution, CRDTs,
+operational transforms, offline-first architecture, or collaborative editing.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. Classify data types to determine the conflict resolution strategy.
+2. Define the consistency model (strong, eventual, causal).
+3. Identify offline requirements and maximum acceptable sync lag.
+
+### During implementation
+- Implement conflict detection at field level, not document level.
+- Use vector clocks or hybrid logical clocks for causal ordering.
+- Design the sync engine as a separate layer from business logic.
+- Handle network partitions gracefully (queue changes, reconcile on reconnect).
+
+### After implementation
+- Test with simulated partitions and concurrent edits.
+- Verify convergence (all clients reach same state eventually).
+- Document conflict resolution strategy per data type.
+
+## Conflict Resolution Strategies
+
+| Strategy | Pro | Con | Use For |
+|----------|-----|-----|---------|
+| LWW (Last Write Wins) | Simple, no user action | Silent data loss | Preferences, status fields |
+| CRDTs | Auto-merge, no conflicts | Limited types, storage overhead | Counters, sets, registers |
+| OT (Operational Transform) | Precise intent preservation | Complex, needs server | Real-time text editing |
+
+## CRDT Catalog
+
+- **G-Counter**: grow-only. Each node keeps own count, total = sum. Use for page views.
+- **PN-Counter**: two G-Counters (increment/decrement). Use for inventory, votes.
+- **LWW-Register**: single value + timestamp, latest wins. Use for simple fields.
+- **OR-Set**: add/remove with unique tags, add-wins bias. Use for carts, tag lists.
+
+## Offline-First Architecture
+
+```
+[Local DB] <-> [Sync Engine] <-> [Remote Server]
+```
+
+- All writes go to local DB first (instant UX, zero latency).
+- Sync engine runs in background, uploads pending changes.
+- On reconnect: pull remote → detect conflicts → resolve → merge.
+- Unresolvable conflicts surface to user (never silently drop).
+
+## Sync Protocols
+
+- **Push-Based**: server pushes via WebSocket/SSE. Lowest latency, needs persistent connection.
+- **Pull-Based**: client polls with cursor. Simple, works everywhere, higher latency.
+- **Hybrid** (recommended): push notification "changes exist" → client fetches via HTTP.
+
+## Optimistic Replication
+- Apply locally immediately, replicate async.
+- On conflict: reconcile via chosen strategy (LWW, CRDT, manual).
+- Rollback if server rejects (revert local, show error to user).
+
+## Vector Clocks
+- Each node maintains a vector of logical timestamps (one per node).
+- Determines causality: happened-before, concurrent, or identical.
+- Concurrent events require conflict resolution; causal events merge cleanly.
+
+## Self-check before task completion
+
+- [ ] Is conflict resolution appropriate for each data type?
+- [ ] Does the system handle network partitions without data loss?
+- [ ] Do all clients converge to the same state eventually?
+- [ ] Is offline support implemented with local-first writes?
+- [ ] Are concurrent edits tested with realistic scenarios?
+- [ ] Is the sync protocol resilient to disconnection/reconnection?
+- [ ] Are unresolvable conflicts surfaced to the user?

package/.mindforge/skills/responsive-native/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: responsive-native
+version: 1.0.0
+min_mindforge_version: 10.4.0
+status: stable
+triggers: responsive native design, adaptive layout mobile, platform-specific UX, mobile accessibility design, gesture handling mobile, mobile UX pattern, responsive breakpoint mobile, dynamic type scaling, safe area design, tablet adaptation, foldable device support, mobile navigation pattern
+---
+
+# Skill — Responsive Native UI & Platform-Specific Design
+
+## When this skill activates
+This skill activates when designing adaptive mobile interfaces, implementing platform-specific UX patterns, ensuring accessibility, handling gestures, or supporting diverse screen sizes including tablets and foldables.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. Define responsive breakpoints and layout strategies for phone, tablet, foldable, and landscape orientations
+2. Review platform design guidelines (Apple HIG, Material Design) to ensure platform-appropriate patterns
+3. Establish accessibility requirements: screen reader support, dynamic type scaling, color contrast, touch target sizes
+4. Plan gesture handling strategy considering platform conventions (iOS swipe gestures vs Android navigation patterns)
+
+### During implementation
+- Use platform-appropriate navigation patterns (iOS tab bar + navigation stack, Android bottom nav + drawer)
+- Implement safe area handling for notched devices (SafeAreaView, WindowInsets, notch cutouts)
+- Support dynamic type scaling — use relative font sizes, test with largest accessibility sizes
+- Implement proper touch target sizes (minimum 44x44pt iOS, 48x48dp Android) with adequate spacing
+- Use semantic colors and avoid hardcoded values to support dark mode automatically
+- Implement platform-specific gesture handlers (swipe back on iOS, hardware back button on Android)
+- Handle keyboard interactions properly (dismiss on scroll, avoid keyboard covering inputs, proper focus management)
+
+### After implementation
+- Test on multiple screen sizes: smallest supported phone, largest phone, tablet, foldable (if applicable)
+- Verify accessibility with screen readers (VoiceOver, TalkBack), ensure all interactive elements are labeled
+- Test with maximum dynamic type size settings and ensure UI remains functional
+- Validate gesture handling: swipe navigation, pull to refresh, long press actions work intuitively
+- Check dark mode appearance, ensure proper contrast and no hardcoded light-mode colors
+
+## Self-check before task completion
+- [ ] Layout adapts correctly across all target screen sizes without clipping or awkward spacing
+- [ ] Platform-specific patterns are used (no Android-style navigation on iOS, and vice versa)
+- [ ] Accessibility score passes WCAG 2.1 AA minimum (contrast ratios, touch targets, screen reader support)
+- [ ] Safe areas are properly handled on devices with notches, rounded corners, and home indicators
+- [ ] Gestures work intuitively and don't conflict with system gestures or platform conventions
+- [ ] Dynamic type scaling is supported with proper layout adjustments for large text sizes

package/.mindforge/skills/responsive-patterns/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: responsive-patterns
+version: 1.0.0
+min_mindforge_version: 0.1.0
+status: stable
+triggers: responsive pattern, mobile first design, container queries pattern, fluid typography, adaptive component design, breakpoint strategy, viewport units, media query architecture, responsive layout pattern, responsive image strategy, css clamp technique, responsive grid system
+---
+
+# Skill — Responsive Patterns
+
+## When this skill activates
+Any task involving responsive layout architecture, mobile-first design, adaptive
+components, fluid sizing, or multi-viewport support.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. Determine if the design is mobile-first or desktop-first (prefer mobile-first).
+2. Identify content-based breakpoints (where the layout breaks, not device widths).
+3. Decide between page-level media queries vs component-level container queries.
+
+### During implementation
+- Use `min-width` media queries for mobile-first progressive enhancement.
+- Apply container queries for reusable components that adapt to their parent.
+- Use fluid typography with `clamp()` for smooth scaling without breakpoints.
+- Prefer CSS Grid for 2D layouts, Flexbox for 1D alignment.
+- Use modern viewport units (`dvh`, `svw`, `lvw`) for mobile Safari compatibility.
+
+### After implementation
+- Test at minimum: 320px, 768px, 1024px, 1440px viewports.
+- Verify no horizontal scroll at any viewport width.
+- Check touch targets are minimum 44x44px on mobile.
+- Validate images load appropriate sizes (not desktop images on mobile).
+
+## Core strategies
+
+### Mobile-First
+```css
+/* Base styles (mobile) */
+.card { padding: 1rem; }
+
+/* Tablet and up */
+@media (min-width: 48rem) {
+  .card { padding: 1.5rem; }
+}
+
+/* Desktop and up */
+@media (min-width: 64rem) {
+  .card { padding: 2rem; }
+}
+```
+
+### Container Queries
+```css
+.card-container { container-type: inline-size; }
+
+@container (min-width: 400px) {
+  .card { display: grid; grid-template-columns: 1fr 2fr; }
+}
+
+@container (min-width: 700px) {
+  .card { grid-template-columns: 1fr 3fr 1fr; }
+}
+```
+
+### Fluid Typography
+```css
+/* Scales from 1rem at 320px to 2rem at 1200px */
+h1 { font-size: clamp(1rem, 0.5rem + 2.5vw, 2rem); }
+
+/* Body text with subtle scaling */
+body { font-size: clamp(0.875rem, 0.8rem + 0.25vw, 1rem); }
+```
+
+### Breakpoint Strategy
+- Do NOT use device-based breakpoints (iPhone, iPad, etc.).
+- Add a breakpoint when content breaks or becomes unreadable.
+- Common content breakpoints: ~30rem, ~48rem, ~64rem, ~80rem.
+- Name tokens semantically: `--bp-compact`, `--bp-medium`, `--bp-wide`.
+
+### CSS Grid Layouts
+```css
+/* Auto-fit responsive grid — no media queries needed */
+.grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, 300px), 1fr));
+  gap: 1.5rem;
+}
+```
+
+### Responsive Images
+```html
+<!-- srcset for resolution switching -->
+<img
+  srcset="image-400.webp 400w, image-800.webp 800w, image-1200.webp 1200w"
+  sizes="(max-width: 48rem) 100vw, (max-width: 64rem) 50vw, 33vw"
+  src="image-800.webp"
+  alt="Description"
+  loading="lazy"
+/>
+
+<!-- picture for art direction -->
+<picture>
+  <source media="(min-width: 64rem)" srcset="wide.webp" />
+  <source media="(min-width: 48rem)" srcset="medium.webp" />
+  <img src="narrow.webp" alt="Description" />
+</picture>
+```
+
+### Viewport Units
+```css
+/* Use dvh for mobile Safari (accounts for address bar) */
+.hero { min-height: 100dvh; }
+
+/* svh = smallest viewport height (address bar visible) */
+.sticky-footer { height: 100svh; }
+```
+
+### Adaptive Components (Slot-Based)
+Design components that render different internal layouts based on container size:
+- Compact: stacked layout, icon-only buttons.
+- Medium: side-by-side layout, abbreviated labels.
+- Wide: full layout, expanded content, additional metadata.
+
+## Anti-patterns to avoid
+- Fixed pixel widths on containers (use max-width + percentage/auto).
+- Device-specific breakpoints (will break on next year's devices).
+- Hiding content with `display: none` at breakpoints (serve less content instead).
+- Using `vw` for font-size without `clamp()` (too small on mobile, too large on 4K).
+- Horizontal scrolling caused by fixed-width elements or overflow.
+
+## Self-check before task completion
+
+Before marking a task done when this skill was active:
+
+- [ ] Layout works at 320px without horizontal scroll?
+- [ ] Typography scales fluidly without jarring jumps?
+- [ ] Images serve appropriate sizes per viewport?
+- [ ] Touch targets are 44x44px minimum on mobile?
+- [ ] Container queries used for reusable component responsiveness?
+- [ ] No device-specific breakpoints in the code?

package/.mindforge/skills/rfc-pipeline/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: rfc-pipeline
+version: 1.0.0
+min_mindforge_version: 10.0.4
+status: stable
+triggers: rfc, spec decompose, dependency DAG, task graph, parallel execution, merge conflict recovery, task pinning, worktree isolation, execution plan, spec-to-tasks, dependency resolution, reproducible execution
+compose:
+  - autonomous-loops
+---
+
+# Skill — RFC Pipeline
+
+## When this skill activates
+
+When a specification, RFC, or feature document needs to be decomposed into
+executable tasks with dependency ordering. Also activates when planning parallel
+work across multiple files or modules, when managing complex multi-step
+implementations, or when explicitly asked to create an execution DAG.
+
+## Mandatory actions when this skill is active
+
+### Step 1 — Parse Spec into Atomic Tasks
+
+Decompose the specification into discrete, atomic tasks where each task has:
+
+- **ID**: unique identifier (e.g., `T001`, `T002`)
+- **Description**: what this task accomplishes
+- **Inputs**: what must exist before this task can start (files, APIs, schemas)
+- **Outputs**: what this task produces (files created/modified, APIs available)
+- **Estimated complexity**: S/M/L
+- **Acceptance criteria**: how to verify the task is done
+
+### Step 2 — Build Directed Acyclic Graph
+
+Construct the dependency graph:
+
+- Each task is a node
+- An edge from A to B means "A must complete before B can start"
+- Detect cycles: if any cycle exists, STOP and report as an error
+- Cycles indicate ambiguous dependencies that must be resolved before proceeding
+- Store edges as explicit `depends_on` arrays per task
+
+### Step 3 — Assign Parallel Waves
+
+Group tasks by dependency depth:
+
+- **Wave 0**: tasks with no dependencies (can start immediately)
+- **Wave 1**: tasks that depend only on Wave 0 tasks
+- **Wave N**: tasks that depend only on tasks in waves < N
+- Tasks within the same wave are independent and can execute in parallel
+- Tasks across waves execute sequentially (Wave 0 completes before Wave 1 starts)
+
+### Step 4 — Pin Tasks to Commits
+
+For reproducibility:
+
+- Record the base commit SHA that the plan was created against
+- Each completed task records the commit SHA of its output
+- If the base branch advances, detect drift and flag affected tasks
+- Pinning ensures any task can be reproduced from a known state
+
+### Step 5 — Execute Waves
+
+Run the plan:
+
+- Execute all tasks in the current wave in parallel
+- Wait for all tasks in the wave to complete before advancing
+- Verify outputs of each task match acceptance criteria
+- If a task fails, halt that dependency chain (other chains continue)
+
+### Step 6 — Merge-Conflict Recovery
+
+When parallel tasks produce conflicting changes:
+
+- Detect conflicts immediately after wave completion
+- Isolate conflicting tasks into a resolution queue
+- Resolve conflicts sequentially (human or automated merge)
+- Re-run acceptance criteria on merged result
+- Never auto-resolve conflicts that touch the same logical block
+
+### Step 7 — Worktree-Based Isolation
+
+For true parallel execution:
+
+- Each parallel task gets its own git worktree (branch from pinned SHA)
+- Tasks cannot see each other's in-progress changes
+- Merge worktrees back to the integration branch after wave completes
+- Clean up worktrees after successful merge
+
+### Output
+
+Store the DAG and execution state in `.planning/rfc/[name]/DAG.json` with schema:
+
+```json
+{
+  "name": "rfc-name",
+  "base_sha": "abc123",
+  "tasks": [...],
+  "waves": [[...], [...]],
+  "status": "in-progress|complete|blocked"
+}
+```
+
+## Self-check before task completion
+
+Before marking a task done when this skill was active:
+
+- [ ] Did I decompose the spec into atomic tasks with clear inputs/outputs?
+- [ ] Did I verify no cycles exist in the dependency graph?
+- [ ] Did I assign tasks to parallel waves correctly?
+- [ ] Did I pin tasks to commit SHAs for reproducibility?
+- [ ] Did I handle (or plan for) merge conflicts between parallel tasks?
+- [ ] Did I store the DAG in .planning/rfc/[name]/DAG.json?
+- [ ] Can each task be executed independently given its inputs?