# Idea > [Project Management] Use when capturing new ideas, feature requests, or concepts for future refinement. - Skill: `duc01226/idea` (Agent Skill) - Install (CLI): `npx skillmds@latest add duc01226/idea` - Raw SKILL.md: https://api.skillmd.com/api/skills/duc01226/idea/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: duc01226 (https://skillmd.com/u/duc01226) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/duc01226/idea --- > Codex compatibility note: > > - Invoke repository skills with `$skill-name` in Codex; this mirrored copy rewrites legacy Claude `/skill-name` references. > - Task tracker mandate: BEFORE executing any workflow or skill step, create/update task tracking for all steps and keep it synchronized as progress changes. > - User-question prompts mean to ask the user directly in Codex. > - Ignore Claude-specific mode-switch instructions when they appear. > - Strict execution contract: when a user explicitly invokes a skill, execute that skill protocol as written. > - Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required `spawn_agent` subagent(s) for that task. > - Do not skip, reorder, or merge protocol steps unless the user explicitly approves the deviation first. > - For workflow skills, execute each listed child-skill step explicitly and report step-by-step evidence. > - If a required step/tool cannot run in this environment, stop and ask the user before adapting. ## Codex Project-Reference Loading (No Hooks) Codex uses static project-reference loading instead of runtime-injected project docs. When coding, planning, debugging, testing, or reviewing, open project docs explicitly using this routing. **Always read:** - `docs/project-config.json` (project-specific paths, commands, modules, and workflow/test settings) - `docs/project-reference/docs-index-reference.md` (routes to the full `docs/project-reference/*` catalog) - `docs/project-reference/lessons.md` (always-on guardrails and anti-patterns) **Missing/stale context route:** If `docs/project-config.json`, the docs index, `lessons.md`, `CLAUDE.md`, `AGENTS.md`, or any task-required reference doc is missing or stale, auto-run `$project-init` or the narrow setup route (`$project-config`, `$docs-init`, `$scan-all`, `$scan --target=`, `$claude-md-init`) before ordinary project-specific work. If Codex mirrors or `AGENTS.md` are missing/stale, ask the user to run `$sync-codex`; do not auto-run it. **Situation-based docs:** - Project structure/architecture/tech-stack/deployment/setup (any layer — backend, frontend, or infra): `project-structure-reference.md` - Backend/CQRS/API/domain/entity changes: `backend-patterns-reference.md`, `domain-entities-reference.md` - Frontend/UI/styling/design-system: `frontend-patterns-reference.md`, `scss-styling-guide.md`, `design-system/README.md` - Spec authoring, `docs/specs/` pathing, or TC format: `feature-spec-reference.md`, `spec-system-reference.md`, `spec-principles.md` - Behavior/public-contract changes or spec-test-code sync: `workflow-spec-test-code-cycle-reference.md` plus the spec docs above - Derived spec indexes/ERDs/reimplementation guides: `spec-system-reference.md` and source Feature Specs under `docs/specs/` - Integration test implementation/review: `integration-test-reference.md` - E2E test implementation/review: `e2e-test-reference.md` - Code review/audit work: `code-review-rules.md` plus domain docs above based on changed files Do not read all docs blindly. Start from `docs-index-reference.md`, then open only relevant files for the task. > **[BLOCKING]** Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval. > **[BLOCKING]** Before each step or sub-skill call, update task tracking: set `in_progress` when step starts, set `completed` when step ends. > **[BLOCKING]** Every completed/skipped step MUST include brief evidence or explicit skip reason. > **[BLOCKING]** If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions. ## Quick Summary **Goal:** Turn a vague product idea into a validated, tech-agnostic, module-anchored backlog artifact ready for `$refine` to convert into a PBI — preserving problem intent without leaking solution or stack choices. **Summary:** - **Purpose:** capture a raw idea as a structured, validated backlog artifact — preserve problem intent, leak no solution/stack, hand a clean narrative to `$refine`. - **Main steps/tasks (run in order):** (1) Gather info — problem/value/users/scope; (2) Generate artifact `IDEA-{YYMMDD}-{NNN}`, status `draft`, from `idea-template.md`; (3) Capture problem statement/value/users; (4) Detect project module via `Glob("docs/specs/*/README.md")` (silent; prompt only if ambiguous); (5) Load feature context (8-12K token budget — entities, BR-/TC- patterns); (6) Save to canonical path; (6.5) **Discovery Interview** — 3-5 ask the user directly; (7) **Validate** — 2-3 ask the user directly; (8) Suggest next → `$refine`. - Two interview gates are NON-NEGOTIABLE: Discovery Interview (Step 6.5, 3-5 ask the user directly items incl. the always-on testability question) AND Validation (Step 7, 2-3 items) — never skip either even for "simple" ideas. - Keep the problem statement strictly tech-agnostic (M1): name no framework/product/language/pattern, and do NOT assign logical IDs — the downstream PBI inherits the clean narrative and owns `FR-`/`BR-` assignment. - Auto-detect the project module silently via `Glob("docs/specs/*/README.md")` and load feature context (8-12K token budget); prompt only when ambiguous. Greenfield (no real code dirs) → skip module detection and NEVER ask about tech stack. - Persist to `team-artifacts/ideas/{YYMMDD}-{role}-idea-{slug}.md` with `t_shirt_size`, then hand off to `$refine` for PBI conversion. > **MANDATORY IMPORTANT MUST ATTENTION** task tracking task to READ project-specific reference doc: > `project-structure-reference.md` — project patterns and structure. Not found → search: project documentation, coding standards, architecture docs. **Workflow:** 1. **Gather Info** — Ask problem, value, scope, target users 2. **Generate Artifact** — Create idea file with ID (`IDEA-YYMMDD-NNN`) + draft status 3. **Detect Module** — Auto-match project module, load feature context from docs 4. **Discovery Interview** — ask the user directly 3-5 structured questions (MANDATORY) 5. **Validate** — Confirm problem statement, scope, stakeholders (MANDATORY) 6. **Suggest Next** — Point to `$refine` for PBI creation **Key Rules:** - Output: `team-artifacts/ideas/{YYMMDD}-{role}-idea-{slug}.md` - Validation NEVER optional — MANDATORY step - Auto-detect module silently; prompt only when ambiguous - MUST ATTENTION include `t_shirt_size` (XS/S/M/L/XL) in artifact for early sizing - **[BLOCKING] Tech-agnostic output (M1):** the problem statement stays tech-agnostic per `docs/project-reference/spec-principles.md` §3 (all modes, not only greenfield) — name no framework/product/language/design-pattern; defer any stack preference to the later tech-research phase. - **M3 Logical-ID Assignment (forward to PBI):** See `.claude/skills/shared/sdd-artifact-contract.md` → "AI-SDD Mandates (M1-M7)" for BLOCKING criteria. An idea is a tech-agnostic business-intent definition only — do NOT assign logical IDs yet. When the idea advances to a PBI (via `$refine`), the PBI assigns logical IDs (`FR-`/`BR-`) as the PRIMARY citation spine and tracks `[Source: namespace/service/id]` abstract-anchor evidence (never physical code coordinates or repository-root paths) in a SEPARATE carrier from the business-intent prose. Keep the idea's problem/value narrative free of source identifiers so the PBI can inherit it cleanly. ## Greenfield Mode > **Auto-detected:** No codebase found (no discovered source directories, no manifest files, no populated `project-config.json`) → greenfield mode. Planning artifacts (`docs/`, `plans/`, `.claude/`) don't count — repository must have actual code directories with content. **When greenfield detected:** 1. Skip module auto-detection (no modules exist yet) 2. Skip `project-structure-reference.md` read (won't exist) 3. Focus broader problem-space: market gap, competitors, differentiation 4. Output tech-agnostic problem statement 5. Enable WebSearch for market/competitor context 6. Increase ask the user directly frequency — capture vision, constraints, team profile, scale expectations 7. **[CRITICAL] NEVER ask about tech stack during idea capture.** Tech stack = research-driven decision AFTER full business analysis (business-evaluation phase). User volunteers preference → acknowledge but defer to tech stack research phase. ## Detailed Workflow ### Step 1: Gather Information - No title → ask: "What's the idea in one sentence?" - Ask: "What problem does this solve?" - Ask: "Who benefits from this?" - Ask: "Any initial scope thoughts?" ### Step 2: Generate Artifact - Template: `.claude/docs/team-artifacts/templates/idea-template.md` - ID: `IDEA-{YYMMDD}-{NNN}` (sequential) - Status: `draft` ### Step 3: Capture Details - Document problem statement, expected value, target users ### Step 4: Detect Project Module **Dynamic Discovery:** 1. Run: `Glob("docs/specs/*/README.md")` 2. Extract module names from paths 3. Match idea keywords against module keywords | Scenario | Action | | -------------------- | ------------------------------------------------------------------------------- | | Clear match | Auto-detect — NEVER show confidence levels | | Ambiguous / no match | Prompt: "Which project module?" + Glob results + "Cross-cutting/Infrastructure" | | 2+ modules detected | Load ALL modules, add all to `related_features` | **If module detected:** 1. Read `docs/specs/{module}/README.md` (first 200 lines) 2. Extract feature list from Quick Navigation section 3. Add to frontmatter: `module: {detected_module}`, `related_features: [Feature1, Feature2]` ### Step 5: Load Feature Context 1. Read module README overview (~2K tokens) 2. Identify closest matching feature(s) 3. Read corresponding feature doc (3-5K tokens) 4. Extract: related entities, existing business rules (BR-{MOD}-XXX), test case patterns (TC-{FEATURE}-{NNN}) **Token Budget:** Target 8-12K tokens total. ### Step 6: Save Artifact - Path: `team-artifacts/ideas/{YYMMDD}-{role}-idea-{slug}.md` - Role: infer from context or ask - Include domain context if detected > **Artifact Path (canonical convention)** — Command `$idea` → base path `team-artifacts/ideas/`, role token `po`, type `idea`. Filename pattern: `{YYMMDD}-{role}-{type}-{slug}.md` → e.g. `260119-po-idea-dark-mode-toggle.md`. Slug = lowercased basename, non-alphanumeric → `-`, trimmed, max 50 chars. ### Step 6.5: Discovery Interview (MANDATORY) Use ask the user directly — 3-5 structured questions. Each MUST ATTENTION have 2-4 options with one marked "(Recommended)". | Category | Purpose | Example | | --------------- | --------------------------------- | ----------------------------------------- | | Problem Clarity | Distinguish problem from solution | "What problem does this solve?" + options | | User Persona | Identify primary user | "Who benefits most?" + role options | | Scope | MVP vs full vision | "What's smallest valuable version?" | | Testability | Define done? | "How would you verify this works?" | | Impact | Business value sizing | "How many users/processes affected?" | | Constraints | Known blockers | "Any technical/business constraints?" | | Scale | Expected load/growth | "How many users/transactions expected?" | > **Greenfield:** NEVER include tech stack questions. Focus on business problem, users, scale, constraints. **Testability Question (ALWAYS include):** "How would you verify this feature works correctly?" — Options: manual test steps, automated test criteria, metric thresholds. Document all answers under `## Discovery Interview`. ### Step 7: Validate Idea (MANDATORY) ask the user directly — 2-3 validation questions: | Category | Example Question | | ------------ | ----------------------------------------------------- | | Problem | "Is the problem statement clear and user-focused?" | | Value | "What's the expected business value or user benefit?" | | Scope | "Any scope boundaries to clarify now?" | | Stakeholders | "Who else should review this idea?" | Document under `## Validation Summary`. Update artifact based on answers. **Validation Output Format:** ```markdown ## Validation Summary **Validated:** {date} ### Confirmed - {decision}: {user choice} ### Action Items - [ ] {follow-up if any} ``` ### Step 8: Suggest Next Step ask the user directly after capture: 1. `$refine` — Refine into PBI (Recommended) 2. `$spec [mode=tests]` — Jump straight to test spec 3. `$plan` — Start implementation planning Output: "Idea captured! To refine into a PBI, run: `$refine {filename}`" Module detected: "Module context from {module} will be used during refinement." ## Output Formats ### Domain Context Section ```markdown ## Domain Context (Project Features) ### Module {module_name} ### Related Features - {Feature1} - [docs link] - {Feature2} - [docs link] ### Domain Entities - **Primary:** {Entity1}, {Entity2} - **Related:** {Entity3} ### Existing Business Rules - BR-{MOD}-XXX: {Brief description} ``` ### UI Sketch Section ```markdown ## UI Sketch ### Layout {Rough ASCII wireframe — see UI wireframe protocol} ### Key Components - **{Component}** — {purpose} _(tier: common | domain-shared | page/app)_ ``` > Search existing libs before proposing new components. > Backend-only idea: `## UI Sketch` → `N/A — Backend-only change. No UI affected.` ## Examples ```bash $idea "Dark mode toggle for settings" # Creates: team-artifacts/ideas/260119-po-idea-dark-mode-toggle.md $idea "Add goal progress tracking notification" # Creates with module context: team-artifacts/ideas/260119-po-idea-goal-progress-notification.md ``` --- ## Workflow Recommendation > **MANDATORY IMPORTANT MUST ATTENTION — NO EXCEPTIONS:** Not already in workflow → MUST ATTENTION use ask the user directly: > > 1. **Activate `workflow-idea-to-pbi` workflow** (Recommended) — idea → refine → artifact-review --type=pbi → story → artifact-review --type=story → prioritize > 2. **Execute `$idea` directly** — run standalone --- ## Next Steps **MANDATORY IMPORTANT MUST ATTENTION — NO EXCEPTIONS** after completing skill, use ask the user directly: - **"$refine (Recommended)"** — Transform idea into actionable PBI - **"$web-research"** — Idea needs market research first - **"Skip, continue manually"** — user decides --- > **[IMPORTANT]** task tracking break ALL work into small tasks BEFORE starting — including tasks each file read. Simple tasks: AI MUST ATTENTION ask user whether to skip. > **External Memory:** Complex/lengthy work (research, analysis, scan, review) → write intermediate findings to `plans/reports/` — prevents context loss, serves as deliverable. > **Evidence Gate:** MANDATORY IMPORTANT MUST ATTENTION — every claim, finding, recommendation requires `file:line` proof or traced evidence, confidence percentage (>80% act, <80% verify first). > **UI Wireframe** — Process visual design input (Figma URLs, screenshots, wireframes) via appropriate tool BEFORE creating wireframes. Use box-drawing ASCII characters for spatial layout. Classify every component into exactly ONE tier: Common (cross-app reusable) / Domain-Shared (cross-domain) / Page (single-page). Duplicate UI code = wrong tier. Search existing component libraries before creating new (>=80% match = reuse). Detail level varies by skill (idea=rough, story=full decomposition). > **AI Mistake Prevention** — Failure modes to avoid on every task: > > **Re-read files after context changes.** Context compaction, resume, or long-running work can make memory stale; verify current files before acting. > **Verify generated content against source evidence.** AI hallucinates APIs, names, claims, and document facts. Check the relevant source before documenting or referencing. > **Check downstream references before deleting or renaming.** Removing an artifact can stale docs, generated mirrors, configs, and callers; map references first. > **Trace the full impact chain after edits.** Changing a definition can miss derived outputs and consumers. Follow the affected chain before declaring done. > **Verify ALL affected outputs, not just the first.** One green check is not all green checks; validate every output surface the change can affect. > **Assume existing values are intentional — ask WHY before changing OR flagging one as a defect.** Before changing or reporting a constant, limit, flag, cutoff, wording, or pattern, read nearby context and history, the CALLER's ordering, and 2+ sibling call sites of the same convention. A doc stating WHAT without WHY is missing rationale, not proof of a missing guard. > **Surface ambiguity before acting — don't pick silently.** Multiple valid interpretations require an explicit question or stated assumption with risk. > **Assert the outcome your system owns, not the intermediate state your infrastructure owns.** When verifying async work, assert the final business state — never the delivery/retry bookkeeping held in shared infrastructure that any co-running process can write. Such a check passes when run alone and flakes the moment anything else shares that infrastructure. > **Keep shared guidance role-relevant.** Universal guidance must help every receiving skill or agent; code-specific obligations belong only in code-specific protocols. > **Critical Thinking Mindset** — Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act. > **Anti-hallucination:** Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination. > **Sequential Thinking Protocol** — Structured multi-step reasoning for complex/ambiguous work. Use when planning, reviewing, debugging, or refining ideas where one-shot reasoning is unsafe. > > **Trigger when:** complex problem decomposition · adaptive plans needing revision · analysis with course correction · unclear/emerging scope · multi-step solutions · hypothesis-driven debugging · cross-cutting trade-off evaluation. > > **Format (explicit mode — visible thought trail):** > > 1. `Thought N/M: [aspect]` — one aspect per thought, state assumptions/uncertainty > 2. `Thought N/M [REVISION of Thought K]: ...` — when prior reasoning invalidated; state Original / Why revised / Impact > 3. `Thought N/M [BRANCH A from Thought K]: ...` — explore alternative; converge with decision rationale > 4. `Thought N/M [HYPOTHESIS]: ...` then `[VERIFICATION]: ...` — test before acting > 5. `Thought N/N [FINAL]` — only when verified, all critical aspects addressed, confidence >80% > > **Mandatory closers:** Confidence % stated · Assumptions listed · Open questions surfaced · Next action concrete. > > **Stop conditions:** confidence <80% on any critical decision → escalate by asking the user directly · ≥3 revisions on same thought → re-frame the problem · branch count >3 → split into sub-task. > > **Implicit mode:** apply methodology internally without visible markers when adding markers would clutter the response (routine work where reasoning aids accuracy). > > **Deep-dive:** see `$sequential-thinking` skill (`.claude/skills/sequential-thinking/SKILL.md`) for worked examples (API design, debugging, architecture), advanced techniques (spiral refinement, hypothesis testing, convergence), and meta-strategies (uncertainty handling, revision cascades). **MUST ATTENTION** apply critical + sequential thinking — every claim needs appropriate traced evidence (`file:line` for repo/code claims; source URL or artifact section for research, product, content, and docs claims); confidence >80% to act, <60% DO NOT recommend. Anti-hallucination: never present guess as fact, admit uncertainty freely, cross-reference independently, stay skeptical of own confidence. **MUST ATTENTION** apply sequential-thinking — multi-step Thought N/M, REVISION/BRANCH/HYPOTHESIS markers, confidence % closer; see `$sequential-thinking` skill. **MUST ATTENTION** apply AI mistake prevention — verify generated content against evidence, trace downstream references before deleting or renaming, verify all affected outputs, re-read files after context loss, and surface ambiguity before acting. ## Prompt-Enhance Closing Anchors **IMPORTANT MUST ATTENTION** follow declared step order for this skill; NEVER skip, reorder, or merge steps without explicit user approval **IMPORTANT MUST ATTENTION** for every step/sub-skill call: set `in_progress` before execution, set `completed` after execution **IMPORTANT MUST ATTENTION** every skipped step MUST include explicit reason; every completed step MUST include concise evidence **IMPORTANT MUST ATTENTION** if Task tools unavailable, maintain an equivalent step-by-step plan tracker with synchronized statuses > **Project Protocol Overlay** — Before executing this skill, resolve any PROJECT overlay rules layered onto it: match this skill's name against the `Target` column of the project's skill-protocol index (`docs/project-reference/skill-protocols-reference.md` by default; a `referenceDocs` entry in `docs/project-config.json` overrides the path), taking the most specific matching tier ONLY — exact name > glob > `*`. **That precedence orders overlays against EACH OTHER, never against this skill.** Read ONLY the matched bodies, resolved as `/.md`; a row's Body link is display text, never a read path. A matched body that is missing or malformed is REPORTED and skipped — never reconstructed from the index Description. No index, or no match -> proceed with no overlay, silently. Full contract: `.claude/skills/project-skill-protocol/references/registry.md`. > > Overlays are **ADDITIVE ONLY**: they ADD rules on top of this skill's own protocol and NEVER replace, override, disable, or reinterpret a rule it already states — removing every overlay must return this skill to exactly its documented behavior. An overlay is a BRIEF, not an authority escalation: it can NEVER waive a workflow gate, git discipline, a review gate, or a user-confirmation gate. A genuine overlay-vs-skill conflict, or two equally-specific overlays that directly contradict -> surface both to the user; NEVER resolve silently. **MUST ATTENTION** resolve project protocol overlays for this skill BEFORE executing — most specific matching tier only (exact > glob > `*`, which ranks overlays against each other, NEVER against this skill), read only matched bodies at `/.md`; a missing or malformed body is reported, never reconstructed. Overlays are ADDITIVE ONLY (they never replace this skill's own rules) and are a brief, NEVER an authority escalation; an equal-specificity contradiction goes to the user. ## Closing Reminders **IMPORTANT MUST ATTENTION Goal:** Turn a vague product idea into a validated, tech-agnostic, module-anchored backlog artifact ready for `$refine` to convert into a PBI — preserving problem intent without leaking solution or stack choices. **IMPORTANT MUST ATTENTION — Main steps (run in order, NEVER skip/reorder):** (1) Gather info; (2) Generate artifact `IDEA-{YYMMDD}-{NNN}` draft from `idea-template.md`; (3) Capture problem/value/users; (4) Detect module via `Glob("docs/specs/*/README.md")`; (5) Load feature context (8-12K budget); (6) Save to canonical path; (6.5) Discovery Interview (ask the user directly 3-5); (7) Validate (ask the user directly 2-3); (8) Suggest next → `$refine`. — why: AI keeps dropping the skill's own mid-pipeline steps; the two gates and module detection are the most-forgotten. **IMPORTANT MUST ATTENTION — Protocols in force (concise digest of the SYNC/shared blocks this skill carries):** - **UI Wireframe:** classify each component into ONE tier; search libs first, reuse ≥80% match. - **AI Mistake Prevention:** verify generated content against evidence, trace downstream references, verify all affected outputs, re-read after context loss, surface ambiguity. - **Critical Thinking:** traced proof per claim; confidence >80% to act; never present guess as fact. - **Sequential Thinking:** multi-step Thought N/M with REVISION/BRANCH/HYPOTHESIS markers and confidence closer. **IMPORTANT MUST ATTENTION** Discovery Interview (Step 6.5) + Validation (Step 7) NEVER optional — run BOTH ask the user directly gates even for "simple" ideas — why: discovery uncovers hidden constraints, validation confirms problem framing; different question categories **IMPORTANT MUST ATTENTION** ALWAYS keep problem statement tech-agnostic (M1, `spec-principles.md` §3, all modes) — name no framework/product/language/design-pattern; defer any stack preference to the later tech-research phase — why: PBI inherits the narrative cleanly downstream **IMPORTANT MUST ATTENTION** in greenfield mode NEVER ask about tech stack — acknowledge a volunteered preference, then defer to the business-evaluation phase — why: stack is a research-driven decision after business analysis, not a capture-time guess **IMPORTANT MUST ATTENTION** task tracking break ALL work into small tasks BEFORE starting — including a task to READ `project-structure-reference.md` (skip in greenfield — it won't exist) **IMPORTANT MUST ATTENTION** validate all decisions with user by asking the user directly — NEVER auto-decide — and NEVER show confidence levels on an auto-detected module match **IMPORTANT MUST ATTENTION** auto-detect module silently via `Glob("docs/specs/*/README.md")` — prompt only when ambiguous or no match; greenfield → skip module detection — why: confirm with `Glob()` evidence, not assumption **IMPORTANT MUST ATTENTION** assign NO logical IDs (M3) — an idea is tech-agnostic business intent only; the downstream PBI owns `FR-`/`BR-` assignment and `[Source: namespace/service/id]` anchors — why: keep the problem/value narrative free of source identifiers so the PBI inherits it cleanly **IMPORTANT MUST ATTENTION** include `t_shirt_size` (XS/S/M/L/XL) in the artifact and keep the feature-context load within the 8-12K token budget — why: early sizing feeds prioritization; over-budget reads dilute attention **IMPORTANT MUST ATTENTION** persist to `team-artifacts/ideas/{YYMMDD}-{role}-idea-{slug}.md`, then hand off to `$refine` for PBI conversion — why: canonical path keeps downstream tooling aligned **IMPORTANT MUST ATTENTION** search existing component libraries before proposing any new UI component (≥80% match = reuse); classify each into exactly ONE tier — why: duplicate UI code = wrong tier **IMPORTANT MUST ATTENTION** cite `file:line` proof or traced evidence for every claim/recommendation, confidence >80% to act, <80% verify first — why: certainty without evidence is the root of hallucination **IMPORTANT MUST ATTENTION** add a final review task to verify work quality **Anti-Rationalization:** | Evasion | Rebuttal | | -------------------------------------------- | ----------------------------------------------------------------------- | | "Idea is simple, skip interview" | NEVER skip — discovery uncovers hidden constraints | | "Module is obvious, skip detection" | Still run `Glob()` — confirm with evidence not assumption | | "Validation is redundant after interview" | ALWAYS run both — different question categories | | "Greenfield check is optional" | Auto-detect is MANDATORY — no manual override | | "User mentioned a framework, capture it" | Stay tech-agnostic — acknowledge, defer to tech-research phase | | "I'll assign FR-/BR- IDs now" | NO logical IDs at idea stage — the PBI assigns them downstream | | "Reuse an existing component? new is faster" | Search libs first — ≥80% match = reuse; new without search = wrong tier | **[TASK-PLANNING]** Before acting, analyze task scope and systematically break it into small todo tasks and sub-tasks using task tracking. **IMPORTANT MUST ATTENTION** the 3 rules to never skip: (1) run BOTH Discovery + Validation ask the user directly gates; (2) keep the problem statement tech-agnostic (no stack/IDs); (3) cite `file:line` evidence, confidence >80% to act. ## Hookless Prompt Protocol Mirror (Auto-Synced) Source: `.claude/.ck.json` + `.claude/skills/shared/sync-inline-versions.md` (`:full` blocks) + `.claude/scripts/lib/hookless-prompt-protocol.cjs` ## [WORKFLOW-EXECUTION-PROTOCOL] [BLOCKING] Workflow Execution Protocol — MANDATORY IMPORTANT MUST CRITICAL. Do not skip for any reason. **Generic portability boundary:** Reusable skills and protocol text stay project-neutral; project-specific conventions are discovered from docs/project-config.json and docs/project-reference/. Apply shared AI-SDD from `shared/sdd-artifact-contract.md`. Read `docs/project-config.json` and `docs/project-reference/docs-index-reference.md`, then open the project reference docs named there. For spec, test-case, behavior-change, public-contract, or `docs/specs/` work, route through the local spec docs named by the docs index: `feature-spec-reference.md`, `spec-system-reference.md`, `spec-principles.md`, and `workflow-spec-test-code-cycle-reference.md` when specs/tests/code must stay synchronized. If either file or a required reference doc is missing or stale, auto-run `$project-init` (or the narrow lower-level route such as `$project-config`, `$docs-init`, `$scan-all`, or `$scan --target=`) before ordinary project-specific work. Any supported AI tool may execute when this shared context and local docs are available. 1. **DETECT:** If the prompt starts with an explicit slash skill/workflow command, execute it directly. Otherwise match the prompt against the workflow catalog and skill list. 2. **ANALYZE:** Choose the best option: execute directly, invoke a skill, activate a standard workflow, or compose a custom step combination. 3. **AUTO-SELECT:** Pick the best option yourself. Do not ask the user to choose between direct execution, skill, standard workflow, or custom workflow. 4. **ACTIVATE:** For a selected workflow, call `$start-workflow `; for a selected skill, invoke that skill; for a custom workflow, sequence custom steps directly; for direct execution, proceed with the task. 5. **CREATE TASKS:** task tracking for ALL workflow/skill/custom steps before execution when the selected path has multiple steps. 6. **PARALLELIZE:** Before executing the task list, tag each task `PAR` (independent inputs + write set disjoint from every other `PAR` task) or `SEQ` (name the blocking dependency), group `PAR` tasks into waves, declare the wave plan, and spawn each wave's sub-agents in ONE message — all-return barrier per wave, fan-out one level deep unless a sub-agent's own definition authorizes further fan-out. Sequential-by-default is a defect when tasks are independent; do not parallelize shared write targets, output-consuming tasks, trivial single-file work, ordering a skill or workflow explicitly fixes, or user-approval gates. 7. **EXECUTE:** Advance per the **Workflow Step Advancement & Parallel Phases** rule in your context instructions — model-driven; a sub-agent completion advances a step identically to an inline call; a parallel-phase group is an all-return barrier (advance only after ALL members return, never serialize it) ## Shared AI-SDD Protocol Markers Source: `.claude/skills/shared/sync-inline-versions.md` ## SYNC:ai-sdd-artifact-contract > **AI-SDD Artifact Contract** — Shared spec-driven development rules stay portable and source-owned. > > 1. Keep reusable AI-SDD principles in `.claude`; put repository-specific paths, commands, owners, products, and formats in project config/reference docs. > 2. Preserve cycle: `spec -> plan -> tasks -> implement -> verify -> update spec/docs`. > 3. Trace every requirement or invariant through decision, task, TC/test, source evidence, and docs/spec update. > 4. Treat code-to-spec extraction as reference-only until accepted by the canonical spec owner. > 5. Any supported AI tool may plan, implement, review, or verify with synced context; using multiple tools is optional. > 6. Update `.claude` source first, then sync generated mirrors; do not manually edit `.agents`, `.codex`, or `AGENTS.md`. — why: mirrors are generated artifacts; hand-edits are overwritten on the next sync > 7. If `docs/project-config.json`, root instruction files, or a required project-reference doc is missing or stale, auto-run `$project-init` or the narrow lower-level route before ordinary project-specific work. > > **Active reference:** `shared/sdd-artifact-contract.md` in the active skills root. --- ## SYNC:ai-sdd-artifact-contract:reminder - **MANDATORY** Apply `shared/sdd-artifact-contract.md`; keep reusable AI-SDD in `.claude` and local rules in project docs. - **MANDATORY** Code-to-spec extraction is reference-only until canonical acceptance; any supported AI tool may execute with synced context. - **MANDATORY** Update `.claude` source before syncing generated mirrors; do not manually edit `.agents`, `.codex`, or `AGENTS.md`. - **MANDATORY** Missing or stale project config, root instruction files, or required reference docs route project-specific work through `$project-init` or the narrow setup route automatically. **[TASK-PLANNING] [MANDATORY]** BEFORE executing any workflow or skill step, create/update task tracking for all planned steps, then keep it synchronized as each step starts/completes. ## [LESSON-LEARNED-REMINDER] [BLOCKING] Task Planning & Continuous Improvement — MANDATORY. Do not skip. Break work into small tasks (task tracking) before starting. Add final task: "Analyze AI mistakes & lessons learned". **Extract lessons — ROOT CAUSE ONLY, not symptom fixes:** 1. Name the FAILURE MODE (reasoning/assumption failure), not symptom — "assumed API existed without reading source" not "used wrong enum value". 2. Generality test: does this failure mode apply to ≥3 contexts/codebases? If not, abstract one level up. 3. Write as a universal rule — strip project-specific names/paths/classes. Useful on any codebase. 4. Consolidate: multiple mistakes sharing one failure mode → ONE lesson. 5. **Recurrence gate:** "Would this recur in future session WITHOUT this reminder?" — No → skip `$learn`. 6. **Auto-fix gate:** "Could `$code-review`/`$code-simplifier`/`$security-review`/`$lint` catch this?" — Yes → improve review skill instead. 7. BOTH gates pass → ask user to run `$learn`. **[CRITICAL-THINKING-MINDSET]** Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act. **Anti-hallucination principle:** Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination. **AI Attention principle (Primacy-Recency):** Put the 3 most critical rules at both top and bottom of long prompts/protocols so instruction adherence survives long context windows. **Goal-driven execution:** Define success criteria first, loop until verified, and stop only when observable checks pass. **Tests verify intent:** Tests must protect business rules/invariants and fail when the protected intent breaks, not only mirror current behavior. ## Common AI Mistake Prevention (System Lessons) - **Re-read files after context compaction.** Edit requires prior Read in same context; compaction wipes read state. Re-read before editing. - **Grep for old terms after bulk replacements.** AI over-trusts find/replace completeness. Grep full repo after bulk edits for missed refs in docs/configs/catalogs. - **Check downstream references before deleting.** Deletions cascade doc/code staleness. Map referencing files before removal. - **After memory loss, check existing state before creating new.** Compaction wipes prior-work memory. Query current state to resume — never blindly duplicate. - **Verify AI-generated content against actual code.** AI hallucinates APIs, class names, method signatures. Grep to confirm existence before documenting/referencing. - **Trace full dependency chain after edits.** Changing a definition misses downstream consumers. Trace the full chain. - **When renaming, grep ALL consumer file types.** Some file types silently ignore missing refs (no compile error). Search code, templates, configs, generated files. - **Trace ALL code paths when verifying correctness.** Code existing ≠ code executing. Trace early exits, error branches, conditional skips — not just happy path. - **Update docs that embed canonical data when source changes.** Docs inlining derived data (workflows, schemas, configs) go stale silently. Update all embedding docs alongside source. - **Verify sub-agent results after context recovery.** Background agents may finish while parent compacted — grep-verify output, don't trust assumed completion. - **Cross-check full target list against sub-agent assignments.** Parallel sub-agents by category miss boundary items. Reconcile union of assignments against target list before proceeding. - **Sub-agents inherit knowledge only from their agent .md definition — use custom agent types, not built-in Explore.** Tool adoption = permission + knowledge + enforcement (numbered workflow step). - **Persist sub-agent findings incrementally, not as a final batch.** Long sub-agents hit cutoffs before final write — findings lost. Instruct append-per-section to report file. - **When debugging, ask "whose responsibility?" before fixing.** Trace caller (wrong data) vs callee (wrong handling). Fix at responsible layer — never patch symptom site. - **Test failure → record a provisional verdict before trace/edit, then investigate.** Use the full five-way taxonomy: SOURCE-WRONG (production violates intent), TEST-WRONG (assertion/setup is stale), TEST-NOT-OPTIMAL (valid but fragile or low-signal test), ENVIRONMENT-BLOCKED (external state prevents a verdict), or AMBIGUOUS (intent/evidence cannot choose safely). Then trace root cause and triangulate against the governing spec (`docs/specs/**` if one exists) AND source. NEVER weaken an assertion, add a skip, relax a timeout, or change source merely to force green. - **Grep ALL removed names after extraction …(truncated)