Plan a Complex Operation

Use this skill when

• •The user provides a detailed spec or requirement document (numbered sections, input/output contracts, preconditions)
• •The task creates or modifies more than ~5 files
• •There are architectural trade-offs (e.g. new resource vs inline API calls, partial-failure strategies)
• •The operation orchestrates multiple API calls with rollback or safety concerns

Do NOT use this skill when

• •The task is a single-file change or a straightforward CRUD addition
• •An existing skill already covers the workflow end-to-end (e.g. add-autotask-special-operation)

Workflow

1. Gather context (parallel)

Read in parallel:

• •The relevant project docs (.docs/) and skills (.cursor/skills/) to understand conventions
• •The source files that will be touched (resource descriptions, executors, constants, AI tools layer)
• •Any reference implementations for similar operations already in the codebase

Search the web (Brave) if the task involves external API behaviour you are unsure about.

2. Identify gaps

Before writing the plan, answer:

• •Are there API endpoints or entities that exist in the external service but are missing from this repo?
• •Does the task require new helpers, or can existing ones be reused?
• •Which files need changes vs which are new?

3. Write the plan

Structure:

1. •Reference docs and skills -- list every .docs/ and .cursor/skills/ file the implementer must read. Include file paths as markdown links.
2. •Scope -- what is in and out, directly from the spec.
3. •Gaps -- repo vs API gaps and chosen approach (e.g. "use direct autotaskApiRequest calls; no new resource needed").
4. •High-level flow -- numbered steps for the orchestrator function.
5. •Files to add or touch -- grouped by concern (resource, constants, AI tools layer, shared executor, docs). Cite file paths and what to change in each.
6. •Data and API details -- endpoint paths, payload shapes, query patterns.
7. •Safety -- idempotency, partial failure, deactivation guards.
8. •Performance -- pagination, throttle, retry.
9. •Test matrix -- minimum scenarios.
10. •Observability -- structured return, counters, latency.
11. •Feedback loop -- which docs/skills to update after implementation.

4. QA the plan

Before presenting to the user:

• •Verify every file path exists in the repo
• •Confirm constant/array names match the actual source (e.g. WRITE_OPERATIONS, SUPPORTED_TOOL_OPERATIONS)
• •Check that no touchpoint from the relevant checklist (.docs/autotask/change-guidelines/ai-tools-special-operation-checklist.md) is missing
• •Ensure the feedback loop section names specific files and specific updates

5. Ask before coding

Present the plan and wait for confirmation. Do not begin implementation until approved.

Key lessons

• •Always reference local docs/skills by path so the implementer (human or AI) can read them. Do not assume familiarity.
• •WRITE_OPERATIONS gate is easy to miss. Any mutating operation must be listed there, not just in SUPPORTED_TOOL_OPERATIONS. Call this out explicitly in the plan.
• •Attachment endpoint paths vary by entity family. Do not assume the pattern from one entity (e.g. TicketNotes/{id}/Attachments/) applies to another (e.g. Companies/{id}/Notes/{id}/Attachments/). Verify in Autotask docs.
• •Large orchestrator operations (>200 lines of business logic) should be split into a dedicated file (e.g. moveConfigurationItem.ts) rather than inlined in the resource executor.
• •Partial-failure strategy must be planned upfront for any operation that creates a record and then performs follow-up steps that can fail.

Reference

• •Plan example: the MoveConfigurationItem plan produced in this repo's planning session
• •Implementation skills: .cursor/skills/add-autotask-special-operation/, .cursor/skills/add-autotask-child-entity/
• •Checklists: .docs/autotask/change-guidelines/ai-tools-special-operation-checklist.md