fecode-cli 1.0.0

package/dist/ui/ThinkingBlock.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+export const ThinkingBlock = ({ durationMs, tokenCount, summary }) => {
+    if (!durationMs || isNaN(durationMs) || durationMs <= 0)
+        return null;
+    const seconds = (durationMs / 1000).toFixed(1);
+    const tokenText = typeof tokenCount === "number" && !isNaN(tokenCount) && tokenCount > 0
+        ? `, ${tokenCount} tokens`
+        : "";
+    const header = `Thought for ${seconds}s${tokenText}`;
+    return (_jsxs(Box, { flexDirection: "column", marginLeft: 2, marginBottom: 0, children: [_jsxs(Box, { children: [_jsx(Text, { color: "gray", dimColor: true, children: "\u25B8 " }), _jsx(Text, { color: "gray", dimColor: true, italic: true, children: header })] }), summary && (_jsx(Box, { marginLeft: 2, children: _jsx(Text, { color: "gray", dimColor: true, italic: true, wrap: "wrap", children: summary.split("\n")[0] }) }))] }));
+};
+//# sourceMappingURL=ThinkingBlock.js.map

package/dist/ui/ThinkingIndicator.d.ts

@@ -0,0 +1,7 @@
+import React from "react";
+export interface ThinkingIndicatorProps {
+    isActive: boolean;
+    label?: string;
+}
+export declare const ThinkingIndicator: React.FC<ThinkingIndicatorProps>;
+//# sourceMappingURL=ThinkingIndicator.d.ts.map

package/dist/ui/ThinkingIndicator.js

@@ -0,0 +1,20 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { useState, useEffect } from "react";
+import { Box, Text } from "ink";
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const INTERVAL_MS = 80;
+export const ThinkingIndicator = ({ isActive, label = "Working..." }) => {
+    const [frame, setFrame] = useState(0);
+    useEffect(() => {
+        if (!isActive)
+            return;
+        const timer = setInterval(() => {
+            setFrame((prev) => (prev + 1) % SPINNER_FRAMES.length);
+        }, INTERVAL_MS);
+        return () => clearInterval(timer);
+    }, [isActive]);
+    if (!isActive)
+        return null;
+    return (_jsxs(Box, { children: [_jsxs(Text, { color: "cyan", children: [SPINNER_FRAMES[frame], " "] }), _jsx(Text, { color: "cyan", children: label })] }));
+};
+//# sourceMappingURL=ThinkingIndicator.js.map

package/dist/ui/TurnView.d.ts

@@ -0,0 +1,13 @@
+import React from "react";
+export interface TurnViewProps {
+    prompt: string;
+    response: string;
+    status: "thinking" | "streaming" | "done" | "error" | "cancelled";
+    error?: string;
+    isLast?: boolean;
+    thinkingMs?: number;
+    thinkingTokens?: number;
+    thinkingSummary?: string;
+}
+export declare const TurnView: React.FC<TurnViewProps>;
+//# sourceMappingURL=TurnView.d.ts.map

package/dist/ui/TurnView.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+import { MessageBubble } from "./MessageBubble.js";
+import { ThinkingBlock } from "./ThinkingBlock.js";
+const SEPARATOR = "─".repeat(48);
+export const TurnView = ({ prompt, response, status, error, isLast = false, thinkingMs, thinkingTokens, thinkingSummary }) => {
+    const isStreaming = status === "streaming" || status === "thinking";
+    const hasError = status === "error";
+    return (_jsxs(Box, { flexDirection: "column", marginY: 0, children: [_jsx(MessageBubble, { role: "user", content: prompt }), _jsx(Box, { height: 0 }), thinkingMs !== undefined && thinkingMs > 0 && (_jsx(ThinkingBlock, { durationMs: thinkingMs, tokenCount: thinkingTokens, summary: thinkingSummary })), _jsx(MessageBubble, { role: "agent", content: response, isStreaming: isStreaming && !response && !hasError, error: hasError ? (error || "An error occurred.") : undefined }), status === "cancelled" && (_jsx(Box, { marginLeft: 2, marginTop: 0, children: _jsx(Text, { color: "gray", dimColor: true, children: "\u2298 Cancelled" }) })), !isLast && (_jsx(Box, { marginTop: 1, marginBottom: 0, children: _jsx(Text, { color: "gray", dimColor: true, children: SEPARATOR }) }))] }));
+};
+//# sourceMappingURL=TurnView.js.map

package/dist/ui/WorkspaceStatus.d.ts

@@ -0,0 +1,20 @@
+import React from "react";
+export interface WorkspaceStatusProps {
+    cwd?: string;
+    branch?: string | null;
+    isClean?: boolean;
+    riskLevel?: string;
+    checkpointRequired?: boolean;
+    approvalRequired?: boolean;
+    modifiedFiles?: string[];
+    stagedFiles?: string[];
+    untrackedFiles?: string[];
+    hasDrift?: boolean;
+    driftReason?: string;
+    isStale?: boolean;
+    staleReason?: string;
+    reconciliationState?: string;
+    formattedOutput?: string;
+}
+export declare const WorkspaceStatus: React.FC<WorkspaceStatusProps>;
+//# sourceMappingURL=WorkspaceStatus.d.ts.map

package/dist/ui/WorkspaceStatus.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+export const WorkspaceStatus = ({ cwd = process.cwd(), branch, isClean = true, riskLevel = "low", checkpointRequired = false, approvalRequired = false, modifiedFiles = [], stagedFiles = [], untrackedFiles = [], hasDrift = false, driftReason, isStale = false, staleReason, reconciliationState, formattedOutput }) => {
+    if (formattedOutput) {
+        return (_jsxs(Box, { flexDirection: "column", borderStyle: "single", borderColor: "gray", paddingX: 1, marginY: 1, children: [_jsx(Box, { marginBottom: 0, children: _jsx(Text, { bold: true, color: "cyan", children: "Git & Workspace Status" }) }), _jsx(Text, { color: "white", children: formattedOutput })] }));
+    }
+    const getRiskColor = (risk) => {
+        switch (risk.toLowerCase()) {
+            case "critical":
+                return "red";
+            case "elevated":
+            case "high":
+                return "yellow";
+            case "low":
+                return "green";
+            case "normal":
+            default:
+                return "cyan";
+        }
+    };
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "single", borderColor: "gray", paddingX: 1, marginY: 1, children: [_jsxs(Box, { justifyContent: "space-between", marginBottom: 0, children: [_jsx(Text, { bold: true, color: "cyan", children: "Git & Workspace Status" }), _jsxs(Box, { children: [_jsx(Text, { color: "gray", children: "Risk: " }), _jsx(Text, { bold: true, color: getRiskColor(riskLevel), children: riskLevel.toUpperCase() })] })] }), _jsxs(Box, { marginTop: 0, children: [_jsx(Text, { color: "gray", children: "Directory: " }), _jsx(Text, { color: "white", children: cwd })] }), branch !== undefined && (_jsxs(Box, { marginTop: 0, justifyContent: "space-between", children: [_jsxs(Box, { children: [_jsx(Text, { color: "gray", children: "Branch: " }), _jsx(Text, { color: "cyan", children: branch || "(detached / none)" }), _jsx(Text, { color: "gray", children: " | State: " }), _jsx(Text, { color: isClean ? "green" : "yellow", children: isClean ? "clean" : "modified" })] }), _jsxs(Box, { children: [_jsx(Text, { color: "gray", children: "Checkpoint: " }), _jsx(Text, { color: checkpointRequired ? "yellow" : "gray", children: checkpointRequired ? "REQUIRED" : "OPTIONAL" }), _jsx(Text, { color: "gray", children: " | Approval: " }), _jsx(Text, { color: approvalRequired ? "yellow" : "gray", children: approvalRequired ? "REQUIRED" : "NONE" })] })] })), hasDrift && (_jsx(Box, { marginTop: 0, children: _jsxs(Text, { color: "yellow", bold: true, children: ["\u26A0 Workspace drift: ", driftReason || "State changed outside session"] }) })), isStale && (_jsx(Box, { marginTop: 0, children: _jsxs(Text, { color: "red", bold: true, children: ["\u26A0 Plan stale: ", staleReason || "Prerequisites or files modified"] }) })), reconciliationState && (_jsxs(Box, { marginTop: 0, children: [_jsx(Text, { color: "gray", children: "Reconciliation: " }), _jsx(Text, { color: "white", children: reconciliationState })] })), modifiedFiles.length > 0 && (_jsxs(Box, { flexDirection: "column", marginTop: 0, children: [_jsxs(Text, { color: "gray", children: ["Modified (", modifiedFiles.length, "):"] }), modifiedFiles.slice(0, 4).map((f, i) => (_jsxs(Text, { color: "yellow", children: ["  ", "M ", f] }, `mod-${i}`))), modifiedFiles.length > 4 && (_jsxs(Text, { color: "gray", children: ["  ... and ", modifiedFiles.length - 4, " more"] }))] })), stagedFiles.length > 0 && (_jsxs(Box, { flexDirection: "column", marginTop: 0, children: [_jsxs(Text, { color: "gray", children: ["Staged (", stagedFiles.length, "):"] }), stagedFiles.slice(0, 4).map((f, i) => (_jsxs(Text, { color: "green", children: ["  ", "A ", f] }, `stg-${i}`)))] })), untrackedFiles.length > 0 && (_jsxs(Box, { flexDirection: "column", marginTop: 0, children: [_jsxs(Text, { color: "gray", children: ["Untracked (", untrackedFiles.length, "):"] }), untrackedFiles.slice(0, 4).map((f, i) => (_jsxs(Text, { color: "gray", children: ["  ", "? ", f] }, `unt-${i}`)))] }))] }));
+};
+//# sourceMappingURL=WorkspaceStatus.js.map

package/dist/ui/index.d.ts

@@ -0,0 +1,26 @@
+export * from "./Header.js";
+export * from "./StatusBar.js";
+export * from "./AppShell.js";
+export * from "./ProgressBar.js";
+export * from "./CurrentStepView.js";
+export * from "./TaskInput.js";
+export * from "./PlanStep.js";
+export * from "./PlanView.js";
+export * from "./ExecutionView.js";
+export * from "./ExecutionTimeline.js";
+export * from "./ApprovalPrompt.js";
+export * from "./RiskNotice.js";
+export * from "./BlockedView.js";
+export * from "./RecoveryView.js";
+export * from "./ReplanView.js";
+export * from "./ResumeView.js";
+export * from "./DiagnosticsView.js";
+export * from "./RunHistoryView.js";
+export * from "./WorkspaceStatus.js";
+export * from "./HelpView.js";
+export * from "./ThinkingIndicator.js";
+export * from "./MessageBubble.js";
+export * from "./TurnView.js";
+export * from "./CommandPalette.js";
+export * from "./ThinkingBlock.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/ui/index.js

@@ -0,0 +1,26 @@
+export * from "./Header.js";
+export * from "./StatusBar.js";
+export * from "./AppShell.js";
+export * from "./ProgressBar.js";
+export * from "./CurrentStepView.js";
+export * from "./TaskInput.js";
+export * from "./PlanStep.js";
+export * from "./PlanView.js";
+export * from "./ExecutionView.js";
+export * from "./ExecutionTimeline.js";
+export * from "./ApprovalPrompt.js";
+export * from "./RiskNotice.js";
+export * from "./BlockedView.js";
+export * from "./RecoveryView.js";
+export * from "./ReplanView.js";
+export * from "./ResumeView.js";
+export * from "./DiagnosticsView.js";
+export * from "./RunHistoryView.js";
+export * from "./WorkspaceStatus.js";
+export * from "./HelpView.js";
+export * from "./ThinkingIndicator.js";
+export * from "./MessageBubble.js";
+export * from "./TurnView.js";
+export * from "./CommandPalette.js";
+export * from "./ThinkingBlock.js";
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "fecode-cli",
+  "version": "1.0.0",
+  "description": "FeCode - Interactive Terminal Coding Assistant",
+  "type": "module",
+  "bin": {
+    "fe": "./dist/index.js",
+    "fecode": "./dist/index.js"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "!dist/**/*.map",
+    "skills"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "fe": "tsx src/index.tsx",
+    "dev": "tsx src/index.tsx",
+    "build": "node bundle.mjs",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@google/genai": "^2.16.0",
+    "dotenv": "^16.6.1",
+    "ink": "^5.1.0",
+    "ink-text-input": "^6.0.0",
+    "openai": "^4.77.0",
+    "react": "^18.3.1"
+  },
+  "devDependencies": {
+    "@fecode/agent": "*",
+    "@fecode/models": "*",
+    "@fecode/shared": "*",
+    "@types/react": "^18.3.12",
+    "ink-testing-library": "^4.0.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}

package/skills/accessibility/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: accessibility
+description: Practical web accessibility implementation, ARIA semantics, keyboard navigation, and focus management.
+category: accessibility
+version: 2.1.0
+---
+
+## When to use
+
+- building interactive components
+- fixing accessibility defects
+- writing semantic HTML
+
+## Instructions
+
+### Project Detection & Existing Rules
+- **Inspect package.json & Configuration**: Check if the project uses specific accessibility linters (`eslint-plugin-jsx-a11y`) or UI component libraries (like Radix or Headless UI) that handle accessibility primitives.
+- **Follow existing patterns**: Integrate with existing accessibility patterns in the project.
+
+### Core Mental Model
+- Accessibility means the interface remains usable across keyboard, screen readers, different input methods, visual abilities, cognitive contexts, and motion preferences.
+- It is not merely "use semantic HTML"—it is about communicating state, identity, and behavior to all users.
+
+## Rules
+
+### Semantic HTML
+Before adding ARIA:
+- Ask whether native HTML already provides the correct semantics.
+- Prefer native elements (`<button>`, `<nav>`, `<main>`) over recreating them with `<div>` and ARIA roles.
+
+### Buttons vs Links
+- Use **buttons** (`<button>`) for actions that change state or trigger behavior on the page.
+- Use **links** (`<a>`) for navigation to new URLs or anchors.
+- Do not create clickable divs when a native element exists.
+
+### Keyboard
+- Every interactive feature must have an intentional keyboard interaction.
+- Check tab order (`tabindex="0"` for interactive elements only, avoid positive `tabindex`).
+- Check activation (Space/Enter).
+- Verify focus visibility.
+- Prevent keyboard traps.
+
+### Focus
+Before removing outlines or focus indicators:
+- Provide an equivalent, clearly visible focus state for keyboard users (`:focus-visible`).
+
+### Forms
+- Ensure inputs have associated labels (`<label for="...">` or `aria-labelledby`).
+- Associate error messaging with inputs using `aria-describedby` or `aria-errormessage`.
+- Provide useful validation messaging and indicate required state (`aria-required="true"` or `required` attribute).
+
+### ARIA
+- Use ARIA to communicate semantics that native HTML cannot express (e.g. `aria-expanded`, `aria-controls`).
+- **Do not add redundant ARIA** (e.g. `<button role="button">`).
+- **Do not use ARIA to repair incorrect markup** when simply changing to the correct native HTML tag solves the problem.
+
+### Dynamic UI
+- For dialogs, menus, popovers, and loading states: focus management must be intentional (e.g., trapping focus inside a modal, returning focus to the trigger on close).
+- Use live regions (`aria-live`) for dynamic validation errors or status updates.
+
+### Motion
+- Respect `prefers-reduced-motion` media queries for animations.
+- Do not make motion the only way information is communicated.
+
+### Color
+- Do not communicate meaning through color alone (e.g., use an icon or text alongside a red border for an error state).
+- Ensure sufficient color contrast.
+
+## Anti-Patterns
+
+- **Clickable divs**
+  - *What*: `<div onClick={handleClick}>Submit</div>`.
+  - *Why*: Divs are not focusable by default and do not respond to Enter/Space keys, making them inaccessible to keyboard/screen reader users.
+  - *Instead*: Use a `<button>`.
+- **Missing labels**
+  - *What*: `<input type="text" placeholder="Search" />` without a label.
+  - *Why*: Screen readers may not read the placeholder, leaving users blind to the input's purpose.
+  - *Instead*: Provide a visible `<label>` or `aria-label`.
+- **Invisible focus**
+  - *What*: `outline: none;` without providing a replacement `:focus` or `:focus-visible` style.
+  - *Why*: Keyboard users lose track of where they are on the page.
+  - *Instead*: Keep the default outline or provide a high-contrast custom focus ring.
+- **Unnecessary ARIA**
+  - *What*: Adding `role="navigation"` to a `<nav>` element.
+  - *Why*: It is redundant and adds noise for screen readers.
+  - *Instead*: Just use `<nav>`.
+
+## Workflow
+
+### Debugging
+- Determine if the issue is a missing semantic element, missing keyboard support, or incorrect ARIA state.
+- Inspect the Accessibility Tree in the browser (if available).
+
+### Verification
+- Verify keyboard navigation manually or via tests.
+- Inspect semantic markup.
+- Run automated accessibility checks (`eslint-plugin-jsx-a11y`, `axe-core`) where available in the project.
+- Do not claim automated accessibility verification succeeded unless a real tool was executed.

package/skills/css/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: css
+description: Cascading Style Sheets architecture, layout, specificty, and modern responsive mechanics.
+category: styling
+version: 2.1.0
+---
+
+## When to use
+
+- writing CSS
+- modifying layouts
+- resolving visual defects
+
+## Instructions
+
+### Project Detection & Existing Rules
+- **Inspect package.json & Stylesheets**: Determine if the project uses plain CSS, CSS Modules, Sass/Less, or utility frameworks (e.g. Tailwind).
+- **Follow existing patterns**: Do not introduce a styling architecture that the project does not use (like dropping in Tailwind classes into a CSS Modules project).
+- **Respect naming conventions**: Use existing class naming conventions (e.g. BEM).
+
+### Core Mental Model
+- **Cascade & Inheritance**: Rules apply based on cascade origin, specificity, and source order. Properties like color and font inherit, while layout properties do not.
+- **Specificity**: Browsers calculate selector weight. Inline > ID > Class/Attribute/Pseudo-class > Element/Pseudo-element.
+- **Source Order**: Later rules win when specificity is equal.
+- **Box Model**: Elements have content, padding, border, and margin. Use `box-sizing: border-box`.
+- **Containing Blocks**: Absolute positioning is relative to the nearest positioned ancestor.
+- **Layout vs Decoration**: Separate properties that affect document flow (flex, grid, width) from decorative properties (color, background).
+
+## Rules
+
+### Layout
+Before using `position: absolute`:
+- Ask whether normal document flow, flexbox, or CSS grid solves the layout more robustly.
+
+### Flexbox vs Grid
+- **Flexbox**: Use for 1-dimensional layouts (a row or a column) where content dictates the size.
+- **Grid**: Use for 2-dimensional layouts where the structural grid dictates the layout.
+
+### Fixed vs Fluid
+- Prefer fluid constraints (`%`, `vw`, `vh`, `fr`) when content and viewport can vary.
+- Avoid rigid fixed widths (`width: 500px`) that will break on mobile devices.
+
+### z-index
+Before increasing `z-index`:
+- Inspect stacking contexts. A high `z-index` inside a lower stacking context will not overlay elements in a higher stacking context.
+- Do not solve every layering problem by setting a huge `z-index` (e.g. `z-index: 9999`).
+
+### Specificity
+Before adding `!important`:
+- Determine which selector or cascade rule is causing the conflict.
+- Avoid specificity escalation by refactoring the selector to match the target's specificity organically.
+
+### Responsive CSS
+- Prefer content-driven breakpoints over excessive device-specific media queries.
+
+### Modern CSS
+- Use custom properties (CSS variables), `clamp()`, `min()`, `max()`, container queries, logical properties, and modern color functions where appropriate.
+- **Browser Support**: Do not force modern features when the project's browser support does not allow them. Check existing CSS files for compatibility clues.
+
+## Anti-Patterns
+
+- **!important everywhere**
+  - *What*: Slapping `!important` on properties that don't apply or just to win a specificity war.
+  - *Why*: It breaks the cascade and makes future maintenance a nightmare of specificity wars.
+  - *Instead*: Find the conflicting rule and match or slightly exceed its specificity organically.
+- **Arbitrary z-index escalation**
+  - *What*: Using `z-index: 99999`.
+  - *Why*: It leads to unpredictable layering and arms races between components.
+  - *Instead*: Manage stacking contexts carefully and use a sensible, planned z-index scale.
+- **Fixed widths for fluid content**
+  - *What*: Setting `width: 800px` on a container.
+  - *Why*: It causes horizontal scrolling or cropping on narrow viewports.
+  - *Instead*: Use `max-width: 800px; width: 100%`.
+- **Deeply nested selectors**
+  - *What*: Writing `.card .body .title span { ... }`.
+  - *Why*: It inflates specificity, making it very hard to override styles later.
+  - *Instead*: Use flatter selector structures (e.g., BEM `.card__title`).
+
+## Workflow
+
+### Debugging
+- Inspect computed styles in the browser (if available) to see which rules are winning.
+- Check the box model (padding, border, margin) to understand element sizing.
+- Inspect layout dimensions, parent constraints, and overflow settings.
+- Verify stacking contexts when diagnosing z-index issues.
+- Do not claim browser inspection is available unless a browser tool is actively being used.
+
+### Verification
+- Ensure the layout responds correctly across narrow and wide simulated viewports.
+- Run project CSS linting (e.g. Stylelint) and build steps to verify syntax.

package/skills/frontend-debugging/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: frontend-debugging
+description: Systematic frontend diagnosis and repair methodology. Apply when a UI component, layout, interaction, or state is broken or behaving unexpectedly. This skill teaches structured debugging — reproduce, inspect, isolate, hypothesize, minimal change, verify — rather than guessing and editing code that looks wrong.
+category: frontend
+version: 1.0.0
+---
+
+# Frontend Debugging
+
+## When to use
+- A UI component renders incorrectly or not at all
+- A layout breaks at a specific viewport width or state
+- An interactive element does not respond as expected
+- A data display shows wrong, missing, or stale information
+- A runtime error appears in the console
+- A CSS or styling rule does not apply as expected
+- A state transition produces unexpected UI behavior
+
+## When not to use
+- Purely backend API issues with no UI impact
+- Writing new features from scratch (use frontend-design instead)
+- Reviewing code quality without a specific failure (use ui-review instead)
+
+## Instructions
+- Do not edit code because something "looks wrong" — form a concrete diagnosis first.
+- Use the existing FeCode tools (list_directory, read_file, search_files) to gather information before hypothesizing.
+- Classify the problem type before attempting a fix: rendering, styling, state, data, event, or environment.
+- Prefer the smallest possible change that fixes the actual root cause over refactoring the surrounding code.
+- Verify the fix resolves the original symptom and does not introduce regressions.
+- Never suppress or hide an error to make verification pass.
+
+## Core Debugging Principle
+
+Follow this sequence:
+
+```
+Symptom
+  → Reproduce
+  → Inspect
+  → Isolate
+  → Hypothesize
+  → Minimal change
+  → Verify
+  → Re-check
+```
+
+Do not skip steps. Skipping reproduction and inspection leads to guessing, which leads to changes that mask symptoms rather than fix causes.
+
+## Step 1: Understand the Symptom
+
+Before touching any file:
+- What exactly is broken? (visual glitch, wrong output, no output, crash, interaction failure)
+- Where does it happen? (specific page, component, viewport, state, user action)
+- When does it happen? (always, sometimes, specific condition, after a particular action)
+- Is it consistent or intermittent?
+- What is the expected behavior vs. the observed behavior?
+
+Do not proceed until you can state the symptom precisely.
+
+## Step 2: Reproduce or Establish the Failing Condition
+
+If you cannot reproduce the problem, you cannot verify the fix.
+
+- Identify the exact path through the application that triggers the failure
+- Identify whether the failure depends on a specific viewport, data state, user action, or environment
+- For intermittent failures, identify the conditions that increase the likelihood
+
+If browser tools are available, inspect:
+- Console errors and stack traces
+- Network requests and failures
+- DOM state at the moment of failure
+- Applied CSS rules
+
+Do not invent browser output when browser tools are unavailable. Work from code inspection instead.
+
+## Step 3: Investigate the Repository
+
+Use FeCode tools to gather information before forming a hypothesis:
+
+```
+list_directory     — understand file structure
+search_files       — find component, class name, or error message
+read_file          — inspect the relevant component, styles, data source
+```
+
+Inspect in this order:
+1. The component where the symptom appears
+2. Its parent component (props, context, state passed down)
+3. Associated styles or class names
+4. Data source or API response shape
+5. State management (local state, context, store)
+6. Routing and navigation (if the issue is page-level)
+7. Configuration (if the issue looks environmental)
+
+Read the actual code — do not rely on assumptions about what it probably does.
+
+## Step 4: Classify the Problem
+
+Before hypothesizing a fix, identify what category the problem belongs to:
+
+| Category | Indicators |
+|----------|-----------|
+| **Rendering** | Component not appearing, wrong element rendered, conditional rendering issue |
+| **Styling/CSS** | Element appears but looks wrong — position, size, color, visibility |
+| **State** | UI shows stale data, updates don't propagate, wrong value displayed |
+| **Data** | Fetched data is wrong, missing, or in an unexpected shape |
+| **Event/Interaction** | Handler not firing, wrong handler attached, event not propagating |
+| **Environment** | Works locally but not in another environment; configuration or API key issue |
+
+Solving the wrong category wastes time. A styling fix will not resolve a state problem.
+
+## CSS and Layout Debugging
+
+When a CSS issue is suspected, reason systematically through:
+
+- **Box model**: `width`, `height`, `padding`, `border`, `margin`
+- **Display**: `block`, `inline`, `flex`, `grid`, `inline-flex`, `none`
+- **Position**: `static`, `relative`, `absolute`, `fixed`, `sticky`
+- **Overflow**: `visible`, `hidden`, `scroll`, `auto` — and which ancestor creates the clipping context
+- **Stacking contexts**: `z-index` only works within the same stacking context
+- **Flex sizing**: `flex-grow`, `flex-shrink`, `flex-basis`, `min-width: 0`
+- **Grid sizing**: explicit vs. implicit tracks, `fr` units, `minmax()`
+- **Specificity**: which rule is actually winning, and why
+- **Inheritance**: some properties inherit unexpectedly
+
+**Common CSS traps:**
+- `overflow: hidden` on a parent clips children with `position: sticky`
+- `min-width` defaults on flex items prevent shrinking — add `min-width: 0`
+- `z-index` on an element inside a stacking context with `z-index: 0` cannot escape it
+- `height: 100%` requires an ancestor with an explicit height
+
+## State and Data Debugging
+
+- Confirm that the data source (API, store, prop, context) is actually returning what you expect
+- Confirm that state updates trigger re-renders where needed
+- Confirm that async operations (fetch, suspense, streaming) are completing before the component tries to render
+- Distinguish between "data is wrong" and "data is correct but rendered incorrectly"
+
+## Step 5: Form a Concrete Hypothesis
+
+Before changing any file, state your hypothesis explicitly:
+
+> "I believe the problem is X, caused by Y, and the fix is Z."
+
+If you cannot form a specific hypothesis, gather more information rather than trying random edits.
+
+## Step 6: Make the Minimal Change
+
+- Fix the root cause, not the symptom
+- Do not refactor the entire component to fix a single CSS property
+- Do not add workaround overrides when the underlying issue can be fixed directly
+- Do not restructure state management when the display logic is wrong
+
+Prefer surgical edits. The more code you change, the more you risk introducing regressions.
+
+## Step 7: Verify
+
+After making the fix:
+1. Re-read the changed code — does it actually address the root cause?
+2. Run any relevant tests or build checks
+3. Mentally or actually reproduce the original failing scenario
+4. Check adjacent states: does fixing one state break another?
+5. Check any related components that may share the affected code
+
+## Debugging Workflow
+
+1. Understand the symptom precisely.
+2. Reproduce or establish the failing condition.
+3. Use list_directory, search_files, and read_file to gather information.
+4. Read the component, its parents, its styles, and its data source.
+5. Classify the problem type.
+6. Form a concrete hypothesis about the root cause.
+7. Make the smallest appropriate change.
+8. Verify: re-read, run checks, reproduce the original scenario.
+9. Confirm the original failure is resolved.
+10. Check for regressions in related states and components.
+
+## Avoid
+
+- Editing code because it "looks like" the problem without verifying through inspection.
+- Changing multiple files simultaneously before understanding the issue — each change obscures what fixed what.
+- Rewriting a component to fix a problem that was in a single property.
+- Adding CSS overrides that mask the real issue rather than correcting it.
+- Hiding errors with try/catch or null checks without addressing the underlying cause.
+- Disabling TypeScript or lint checks to make verification pass — if they flag something, investigate it.
+- Declaring success before reproducing the original scenario with the fix applied.
+- Inventing browser console output when browser tools are unavailable.
+
+## Examples
+
+### Example: Diagnosing layout overflow before editing
+
+Wrong approach: "The component looks too wide, I'll add `overflow: hidden` to the parent."
+
+Correct approach: Identify which specific element is causing overflow. Check `min-width` on flex children (common culprit). Inspect the box model of the overflowing element. Fix the constraint that prevents correct shrinking, not the visibility of the overflow.
+
+### Example: State vs. rendering classification
+
+Symptom: "The user's name shows the old value after they update their profile."
+
+Classify first: Is the API returning the old value? Is the store not updating? Is the component not re-rendering? Is it re-rendering but showing a stale closure value? Each of these has a different fix. Read the data flow before editing.