---
name: drupal-clickup-docs
description: 'Manage ClickUp documentation and project documentation for AI-assisted Drupal work. Use when: adding to ClickUp wiki, creating technical analysis documents, updating ClickUp ticket descriptions, posting documentation to a ClickUp space, logging AI-assisted work, creating a docs folder in a module, updating the project-level docs folder, documenting session changes, tracking work in ClickUp tickets, writing or updating ClickUp comments. DO NOT use this skill for Lando or Terminus commands — those belong to Atlas.'
---

# ClickUp Documentation & Project Docs

## When to Use
- User says "Add to wiki", "Document this", "Post to ClickUp", "Create a doc"
- End of a development session involving AI-assisted code changes
- Creating or updating a module `docs/` folder entry
- Updating the project-level `docs/` folder for cross-module or architectural decisions
- Updating a ClickUp ticket description or comment

---

## MCP Connection Check

**Before any ClickUp operation**, verify the MCP server is connected by checking for `mcp_clickup_*` tools.

If not available, show the developer:

```
ClickUp MCP Setup Required

1. VS Code Settings (Cmd/Ctrl+,) → Extensions → GitHub Copilot → MCP Servers
2. Add MCP Server:
   - Name: clickup
   - Command: npx
   - Args: -y @modelcontextprotocol/server-clickup
3. Add environment variable: CLICKUP_API_TOKEN=<your token>
   Get token from: https://app.clickup.com/settings/apps
4. Reload window (Cmd/Ctrl+Shift+P → "Reload Window")
5. Verify: ask Copilot to list ClickUp workspaces
```

---

## Critical API Formatting Rules

These are non-negotiable — get them wrong and the API call fails or produces broken output.

### Ticket / Task descriptions
- **Accept Markdown** — use full Markdown formatting (headings, bold, lists, code blocks)
- Update via `mcp_clickup_clickup_update_task` with the `description` field

### Document pages (Wiki)
- **Accept Markdown** — use full Markdown in the `content` field
- Create: `mcp_clickup_clickup_create_document_page`
- Update: `mcp_clickup_clickup_update_document_page`

### Task comments
- **Plain text ONLY — no Markdown** — asterisks, hashes, backticks appear as literal characters
- Unicode is permitted (✅, →, em-dash, etc.)
- Use `mcp_clickup_clickup_create_task_comment`
- Structure comments using blank lines and Unicode for visual separation instead of Markdown syntax

**Comment formatting example (correct):**
```
Summary of AI-assisted changes — 2026-04-03

Files changed:
  • web/modules/custom/mymodule/src/Service/MyService.php
  • web/modules/custom/mymodule/mymodule.services.yml

What was done:
Refactored MyService to use constructor injection. Added cache tag invalidation on entity save.

Tested: local Lando environment ✅
```

---

## Project Documentation Rules

### Module-level docs
When AI assists with work **inside a specific custom module**, maintain a `docs/` folder in that module:

```
web/modules/custom/mymodule/
└── docs/
    ├── PLAN.md        ← architecture decisions, planned approach
    └── CHANGES.md     ← log of AI-assisted changes, one entry per session
```

- `PLAN.md` — written before or during development. Describes the intention.
- `CHANGES.md` — append-only log. Each entry: date, what changed, why, files affected.

### Project-level docs
When work spans multiple modules or is architectural in nature, document in the project root `docs/` folder:

```
docs/
└── ai-changes/
    └── YYYY-MM-DD-brief-description.md
```

Naming: `2026-04-03-refactor-entity-save-hooks.md`

### What every documentation entry must include
1. Date and session context
2. What was built or changed (with file paths)
3. Why (the problem being solved)
4. Any decisions made that aren't obvious from the code
5. Anything that could affect other developers

---

## ClickUp Documentation Workflow

### "Add to Wiki" trigger
When user says "Add to wiki", "Document this", or similar:

1. **Check MCP connection** (see above)
2. **Check for an active GitHub PR** on the current branch — if found, include the PR link in the document
3. **Ask which ClickUp Space** if not clear from context: *"Which ClickUp Space should this go to?"*
4. **Locate the Space** using `mcp_clickup_clickup_get_workspace_hierarchy` or search
5. **Find the parent page** — look for "Technical Analyses", "Documentation", or "Knowledge Base" sections
6. **Create a new subpage** — always a new page unless user says "update existing"
7. **Confirm** with the page link

### Document page structure
```markdown
# [Feature/Analysis Title]

**Date:** YYYY-MM-DD
**Developer:** [name if known]
**Related PR:** [#123 — PR Title](URL) ← include if branch has a PR

---

## Summary
[2–3 sentence executive summary]

## Context
[The problem or requirement being addressed]

## Technical Details
[Implementation details, architecture decisions, code patterns]

## Files Changed
- `path/to/file.php` — brief description

## Decisions Made
[Any non-obvious choices and why]

## Testing
[How this was verified]
```

### Ticket description update
Use `mcp_clickup_clickup_update_task` with the `description` field. Descriptions accept Markdown — use it fully.

### Adding a comment to a ticket
Use `mcp_clickup_clickup_create_task_comment`. **Plain text only.** See formatting rules above.

---

## GitHub PR Integration

Before creating any ClickUp document, check if the current branch has an associated PR:
- If yes: include `Related PR: [#N — Title](URL)` prominently at the top of the document
- If no PR exists: omit the field, do not fabricate a link

---

## Space Discovery Tips
- Search by client or project name first
- Common section names: "Technical Analyses", "Documentation", "Knowledge Base", "Dev Notes"
- When uncertain, ask the developer: *"What's the ClickUp Space name for this project?"*
