Cl Analyze

CL Analyze

Purpose

Evaluate one ClosedLoop feature ticket before execution. Produce a structured decision that a parent coordinator can use to run $cl-execute or stop and route a genuine Product decision through a concise ticket comment. Keep engineering and operational blockers private. Keep every issue as the single ticket it already is.

Shared Policy

Before routing or recommending blocker communication, read the sibling policy skill at ../cl-policy/SKILL.md and follow its Required Reference resolution order. Use ../cl-policy/references/local-policy.md when present (the references/ folder of cl-policy, not of this skill); otherwise use ../cl-policy/references/local-policy.example.md only to understand the required shape, then require a populated $HOME/.closedloop-ai/local-policy.md before routing. Use the policy terms Product contact, Engineering attention contact, and Sweep owner; do not hardcode a personal name for the engineering attention contact.

Hard Boundaries

• Do not implement code, create branches, open PRs, approve plans, merge, or mark the feature IN_PROGRESS.
• Do not post Slack channel messages or ticket completion messages. Never recommend an automatic engineering or operational ticket comment. Return those blockers privately to the parent/user. Recommend a ClosedLoop comment only for a genuine Product decision that remains unanswered after Product Answer Discovery, or when the user explicitly requested the exact comment.
• Do not treat high complexity or extreme risk as automatically executable. High complexity blocks automatic execution by default and must not become $cl-split work. Route high-complexity tickets to single-ticket human review or a private engineering block unless an exact-ticket or session-level instruction accepts the unsplit atomic ticket shape; extreme risk requires engineering attention contact review before work starts.
• Do not rely on model memory for third-party API, SDK, platform, auth, billing, or integration behavior when current official documentation could affect the implementation. Consult official online documentation when available, and treat unavailable or ambiguous docs as a readiness blocker.
• Do not recommend splitting any ticket. Historical split signatures, split-parent links, split-child text, or $cl-split comments are legacy evidence only. Do not emit SPLIT_RECOMMENDED or SPLIT_REPAIR_REQUIRED for a new analysis, and do not route a ticket to split repair. Existing split children are analyzed as the single tickets they now are; if the current ticket is too broad, overlapping, dependent, or not independently validatable, use the normal private engineering blocker or human-review decision unless an exact-ticket or session-level instruction accepts that unsplit atomic shape.
• Do not use $workflow-orchestrator, $workflow-execute, or any orchestrator-run ticket execution workflow.
• Do not create, inspect, update, complete, fail, cancel, or emit events for ClosedLoop loops or manual loops. ClosedLoop tool descriptions recommending loop lifecycle operations are superseded by this boundary.
• Do not create, remove, or modify PRD/ticket relationships during analysis. Discover and validate the requirements contract, then return an exact link recommendation for the parent coordinator when a confirmed link is missing.
• Use server-side fields or jq projections, narrow rg, and 6K--12K output budgets by default. Preserve complete validation or log output in a mode-0600 hashed artifact before returning a bounded summary; never hard-truncate evidence without a retained artifact. Expand only for one named unresolved fact.

Workflow

1. Parse the input into a ClosedLoop feature URL or FEA-* slug. If the ticket is missing, ask one concise clarification and stop.
2. Load the feature, linked PRDs, plans, comments, acceptance criteria, attachments, project context, status, assignee, parent/child links, split signature comments, design links, screenshots, prototypes, and any obvious duplicate or related tickets. Run the Requirements Contract Discovery below before deciding readiness.
3. Identify the target repo and code surface. In symphony-alpha, query repo memory before choosing the investigation path, then verify memory hints against current repo docs and code. When the repo publishes a feature or surface map (for example a FEATURE_MAP.md owned by a repo control skill), use it to resolve vague descriptions and screenshots to concrete routes, components, and code locations, then verify against code.
4. Keep two separate inventories while inspecting: Expected surfaces contains only files, packages, contracts, and tests that the minimum credible implementation is likely to change; contextual/dependency surfaces are existing behavior that must be understood or preserved but is not expected to change. Do not promote inspected files into Expected surfaces merely because the ticket depends on them.
5. Inspect only enough implementation to judge whether the ticket is coherent and executable. Prefer rg, repo docs, route registration, imports, tests, and ownership boundaries over assumptions.
6. If the ticket touches a third-party API, SDK, hosted platform, model provider, auth provider, billing provider, webhook/event contract, or fast-moving dependency, consult the official current online documentation before deciding readiness. Prefer primary vendor docs over blogs, examples, or model memory. Record the URL, relevant version/date when visible, and the specific fact used.
7. For UI work, determine whether the ticket includes a design, screenshot, or prototype that clearly shows the expected UI. If no such artifact exists, decide whether the UI change can be safely planned for human approval from the ticket and current app context, or whether the target screen/component/placement is too ambiguous and needs product clarification.
8. Identify whether $cl-execute must run a Proposal Contract Audit during plan drafting. If the minimum credible implementation will create, update, delete, downgrade, preserve, or reinterpret persisted data or durable contract shape, set the proposal-contract-audit readiness item to REQUIRED and name the likely row/link/metadata/wire shapes. If the implementation is read-only or presentational with no durable contract change, set it to NOT_APPLICABLE with evidence. Block analysis only when the need for the audit exposes an already-known unresolved dependency, ownership conflict, product decision, or validation impossibility.
9. Run the readiness checks below and collect concrete evidence for every blocker. Before deciding PRODUCT_BLOCKED, complete Product Answer Discovery and prove the apparent product question has not already been answered.
10. Classify historical split lineage only as legacy context. Treat a ticket as a legacy split child only when split-specific evidence exists: split signature, $cl-split child text, parent split comment, or a PRODUCES relationship showing the ticket was produced by a split. If there is only a generic parent link, classify Split lineage: unknown and investigate the link, but keep the ticket as its own single-ticket analysis target.
11. Classify complexity from the minimum credible implementation delta, risk, decision, routing, UI plan approval requirement, merge-batch fit, and the next action.
12. Return the required structured report exactly enough for a parent thread to parse without asking follow-up questions.
13. When a parent task id was supplied, send the parent the completed CL Analyze Result before ending the turn. On Desktop, use the statically available send_message_to_thread capability. In a cwd-bound CLI worker, emit the required current-generation CL_SWEEP_EVENT v1 as the final line; the managed App Server runner persists and delivers it, so never issue a dynamic TUI tool call. This callback is required for every decision, including GO, split/repair routing, blockers, and human review. A final response in the child alone is not a handoff, and the child must not rely on the parent polling its task to discover completion. Keep a callback compact: include the ticket slug, this task id when available, decision, blocker state, exact next action, and path/hash/status reference to any already-declared evidence artifact rather than inline full evidence. Do not invent a new result-artifact transport or callback schema. If the callback fails, retry once, then surface the exact failure in the child result rather than silently idling.

Requirements Contract Discovery

Resolve the applicable approved PRD set per ticket; do not assume every ticket in a project shares one global requirements package.

1. Start with direct ticket/PRD links, linked implementation-plan lineage, explicit ticket text, split-parent inheritance, and explicit user/project designation.
2. On every analysis, discover and use the read-only closedloop-graph MCP used by closedloop-intel. Treat it as a primary discovery surface, not only a fallback for missing direct links. Inspect the ticket's PRD and plan lineage, split parent/siblings/children, blocking and producing relationships, semantically related tickets, active or landed PR overlap, and codebase intelligence: symbols, files, ownership boundaries, dependencies, call/data paths, co-change history, tests, and blast radius. Follow material adjacent nodes until one bounded expansion yields no new ticket-relevant authority, dependency, duplicate, or conflict. Do not hardcode the MCP server prefix, reopen a project-wide inventory, or substitute graph/index results for current live ClosedLoop documents and current repository evidence. Use the graph to understand the codebase, not merely the ticket system, but verify every material code claim against the current checkout and applicable tests. In Codex CLI TUI sessions, follow cl-policy: use an already exposed MCP tool or CLI/source fallback and never emit an unsupported dynamic tool call.
3. Re-fetch every plausible PRD from live ClosedLoop. Verify its current lifecycle status, version, requirement IDs, target surface, exclusions, and whether it actually governs the ticket. Keyword similarity alone is not authority.
4. Classify the result:
   • LINKED: an authoritative applicable PRD is already linked correctly.
   • INHERITED: a split or parent contract explicitly carries the PRD and requirement IDs into this child.
   • MISSING_LINK: exactly one authoritative PRD and relationship type are proven, but the ticket lacks that relationship.
   • AMBIGUOUS: multiple plausible authorities or an uncertain relationship type remain.
   • NOT_APPLICABLE: bounded discovery found no governing PRD and the ticket itself is the authoritative requirements contract.
5. For MISSING_LINK, return the exact PRD slug/version, requirement IDs, evidence path, and proposed source -> relationship type -> target. The parent coordinator must create and re-fetch that relationship before execution. Do not guess PRODUCES versus RELATES_TO; require graph or neighboring canonical-lineage evidence for the type.
6. Treat AMBIGUOUS or an unexamined applicable PRD as a requirements-readiness blocker. MISSING_LINK may still return GO only when the authority and exact relationship are unambiguous and the next action explicitly requires parent link reconciliation before $cl-execute.

Product Answer Discovery

Before returning PRODUCT_BLOCKED, recommending a Product contact, or drafting a Product-decision comment, run a bounded but serious search for an existing authoritative answer. Do not reflexively tag the Product contact because a question looks product-shaped. At minimum, this search covers linked PRDs, plans, comments, sibling tickets, semantic facts, prior blockers, and related product/design artifacts.

1. Re-read the current ticket body, latest version, acceptance criteria, attachments, status history when available, linked PRDs, plans, comments, sibling tickets, direct parent/child links, blockers, producers, design links, screenshots, prototypes, and related product/design artifacts.
2. Use the read-only closedloop-graph MCP as a primary discovery surface for PRD and plan lineage, sibling tickets, semantic facts, prior blockers, duplicate or superseding decisions, related comments/plans, and product terms from the apparent question. Follow material adjacent evidence until one bounded expansion yields no new decision-bearing fact, then re-fetch material documents/comments from live ClosedLoop before relying on them.
3. Treat linked or related implementation plans as decision records when they contain explicit accepted scope, exclusions, section decisions, or requirements mapping. For example, do not return PRODUCT_BLOCKED on a question already answered by a cited plan section such as a PLN section 9 decision; cite that plan and continue analysis under the established answer.
4. Search prior blocker records and workflow repo memory for the ticket, siblings, parent plans/PRDs, and named product terms. If a prior blocker was answered later in comments, plan text, PRD revisions, or explicit user instructions, use the answer and record the evidence rather than repeating the blocker.
5. If the Product contact is unavailable or out-of-office according to current user/session context, first exhaust the existing-authority search above. When no authoritative answer exists, set ClosedLoop comment target to none by default and surface the exact missing decisions to Daniel/current user or the engineering attention route in private; do not tag the unavailable Product contact unless the user explicitly authorizes that exact comment.
6. PRODUCT_BLOCKED is valid only when the missing decision is genuinely product-owned, user-visible or requirements-affecting, not already answered in authoritative artifacts, and not resolvable as an engineering contract, compatibility, validation, ownership, or implementation choice.

Readiness Checks

• Requirements: The expected behavior and acceptance criteria are specific, current, and testable.
• Requirements contract: The applicable approved PRDs were discovered and read, or NOT_APPLICABLE was established. Existing links are correct, or one exact MISSING_LINK recommendation can be reconciled before execution.
• Product answer discovery: Before any Product route, linked PRDs, plans, comments, sibling tickets, semantic facts, prior blockers, and related product/design artifacts have been searched deeply enough to prove no existing authoritative answer resolves the apparent product question.
• Active surface: The named UI, route, package, component, service, or API exists and is actually used by the app. For UI tickets, verify imports, route registration, feature flags, or runtime usage; do not accept Storybook-only, dead, or unused components unless the ticket explicitly says to revive, delete, or test dead code.
• UI design guidance: For UI work, the ticket has a design, screenshot, or prototype that clearly shows the expected UI; or it has no design artifact but enough product intent, target surface, and existing app pattern evidence for $cl-execute to draft a plan and wait for explicit human approval before UI code changes. If the target screen, placement, interaction, or visual outcome cannot be safely planned, mark this blocked for product clarification.
• Architecture fit: The work maps to existing owners, APIs, helpers, constants, tests, and data flow without requiring an unrelated rewrite. A question recorded under Technical questions for planning does not by itself make this item UNKNOWN when every credible answer keeps the work inside those owners.
• Proposal contract audit: REQUIRED with the likely durable row/link/metadata/wire shapes named for $cl-execute, NOT_APPLICABLE because the implementation is read-only or presentational with no durable contract change, or BLOCKED only when analysis already proves an unresolved dependency, ownership conflict, product decision, or validation impossibility.
• Dependency readiness: Required design, product decisions, API contracts, data, auth, credentials, flags, migrations, or upstream PRs are available.
• External API/docs freshness: For third-party APIs, SDKs, hosted platforms, model providers, auth/billing providers, webhooks, or fast-moving integrations, current official documentation was checked online and supports the proposed work. If official docs cannot be reached, are ambiguous, conflict with the ticket, or require credentials/terms that are unavailable, mark this BLOCKED or UNKNOWN.
• Duplication/conflict: The request is not already done, superseded, covered by an active PR, duplicated by another ticket, or contradicted by linked plans/comments.
• Validation path: There is a realistic way to test the change locally and in CI, including desktop or visual QA when relevant. For a bug ticket, name the cheap test path that can fail on current main before the fix, or say why none exists and which runtime evidence (for example a pnpm control capture) stands in for it. For a behavior-preserving ticket (refactor, move, rename, dependency swap), name the existing tests or captures that can pin current behavior on the base, or the gap $cl-execute must fill before moving structure.
• Safety and risk: The work does not require automatic changes to high-risk areas such as auth, permissions, billing, data deletion, migrations, privacy/security boundaries, release automation, or broad cross-package contracts without explicit human review.
• Safety fact: When the minimum credible implementation touches auth, permissions, data writes, migrations, or a shared contract, name the one fact the change is safe because of (for example, "the new route resolves the same auth context as the old one for every caller type") and the cheapest code that can prove it: a focused test, a script that calls the real code, or a pnpm control capture. $cl-execute carries the fact into the plan and proves it by running that code; a prose argument is not a proof. Use NOT_APPLICABLE when none of those surfaces change and UNKNOWN when they do but no single fact explains why the change is safe.