Docs and Skills Feedback Loop

Use this skill when

• •An implementation is complete and you need to push lessons back into .docs/ and .cursor/skills/
• •A new pattern was introduced that is not yet documented (e.g. dedicated orchestrator file, rolling throttle, partial-failure option)
• •A gotcha or silent-failure mode was discovered during implementation or QA
• •An existing instruction was found to be wrong or misleading

Do NOT use this skill when

• •The change was trivial (single-file fix, typo, no new patterns)
• •The docs and skills already cover the pattern accurately

Workflow

1. Identify what changed

Review the implementation diff and ask:

• •Did I introduce a new file layout pattern? (e.g. splitting a large operation into its own module)
• •Did I hit a runtime bug that compiles and lints clean? (e.g. missing normaliseOperation case, missing WRITE_OPERATIONS entry)
• •Did I discover an API behaviour that contradicts or is missing from existing docs? (e.g. attachment endpoint path differs between entity families)
• •Did I add a new category of concern? (e.g. throttle policy, partial-failure strategy, audit notes)

2. Locate the target docs/skills

3. Write minimal, targeted updates

Rules:

• •Add, do not rewrite. Append new sections, hazards, or quality-gate items. Do not restructure the whole doc.
• •Be specific. Name the exact file, constant, or function. ("Add to WRITE_OPERATIONS in AutotaskAiTools.node.ts" not "update the safety gate".)
• •Keep it short. A hazard entry is 3-5 lines. A quality-gate item is one checkbox line. A new section is a heading + a paragraph + an example if needed.
• •No filler. If the lesson is "this worked exactly as documented", there is nothing to add.

4. Verify

• •Read back the updated doc/skill and confirm the new content is consistent with its surroundings (tone, heading level, terminology).
• •Run corepack pnpm build and corepack pnpm lint if any .ts file was touched alongside the doc update.

Examples of good feedback

New hazard (3 lines):

### Missing write-operation gating in `WRITE_OPERATIONS`

If a mutating special operation is added to `SUPPORTED_TOOL_OPERATIONS` but omitted from `WRITE_OPERATIONS`, the operation bypasses the `allowWriteOperations` safety gate.

**Rule:** Any operation that can change data must be listed in `WRITE_OPERATIONS`.

New quality-gate item (1 line):

- [ ] `WRITE_OPERATIONS` — operation listed if operation mutates data

New attachment caveat (added to child-entity template):

5. **Do not assume attachment endpoint shape across entities**:
   - Ticket attachment: `Tickets/{ticketId}/Attachments/{attachmentId}/`
   - Company note attachment (parent chain): `Companies/{companyId}/Notes/{noteId}/Attachments/{attachmentId}/`
   - Always verify the exact endpoint in Autotask docs before implementing.

Anti-patterns

• •Rewriting an entire doc because one section needed a paragraph -- scope the edit.
• •Adding a lesson that restates what the doc already says -- read first.
• •Writing generic advice ("be careful with APIs") instead of specific hazards with file/function names.
• •Skipping this step because the implementation is done -- the feedback loop is part of the definition of done.