claude-plugins/gestao/skills/clip-issue/SKILL.md

---
name: clip-issue
description: Criar e gerir issues Paperclip — lançar objectivos ao CEO, ver progresso, comentar. Usar quando "clip issue", "criar issue", "lançar objectivo", "ver issues clip". Issues seguem cadeia de delegação hierárquica.
context: fork
---

# /clip-issue — Gerir Issues Paperclip

Modos: lista (sem args), criar (com titulo), ver (com ID).

## Constantes

```
BD: PGPASSWORD="paperclip" psql -h localhost -p 54329 -U paperclip -d paperclip
COMPANY_ID: ebe10308-efd7-453f-86ab-13e6fe84004f
API: http://localhost:3100/api
```

## Modo lista (sem argumentos)

```sql
SELECT i.id, i.title, i.status, i.priority, a.name as assignee, i.created_at
FROM issues i LEFT JOIN agents a ON i.assignee_agent_id = a.id
WHERE i.company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
AND i.status NOT IN ('done','cancelled')
ORDER BY
  CASE i.priority WHEN 'critical' THEN 1 WHEN 'high' THEN 2 WHEN 'medium' THEN 3 ELSE 4 END,
  i.status, i.created_at DESC;
```

Para ver concluidas tambem:
```sql
-- Adicionar: AND i.status IN ('done') AND i.updated_at > NOW() - INTERVAL '7 days'
```

## Modo criar (com titulo)

### Passo 1: Obter CEO ID

```sql
SELECT id FROM agents
WHERE company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
AND name = 'CEO';
```

### Passo 2: Criar issue

Preferir API (quando JWT funciona):
```bash
curl -s -X POST "http://localhost:3100/api/companies/ebe10308-efd7-453f-86ab-13e6fe84004f/issues" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "{{TITULO}}",
    "description": "{{DESCRICAO}}",
    "priority": "{{PRIORIDADE}}",
    "assigneeAgentId": "{{CEO_ID}}"
  }'
```

Fallback via BD (OBRIGATORIO incluir identifier e issue_number):
```sql
-- Passo 2a: Obter proximo numero
SELECT issue_counter FROM companies WHERE id = 'ebe10308-efd7-453f-86ab-13e6fe84004f';
-- Guardar o valor como NEXT_NUM

-- Passo 2b: Criar issue COM identifier
INSERT INTO issues (id, company_id, title, description, priority, assignee_agent_id, status, identifier, issue_number, created_at, updated_at)
VALUES (
  gen_random_uuid(),
  'ebe10308-efd7-453f-86ab-13e6fe84004f',
  '{{TITULO}}',
  '{{DESCRICAO}}',
  '{{PRIORIDADE}}',
  '{{CEO_ID}}',
  'todo',
  'DES-{{NEXT_NUM}}',
  {{NEXT_NUM}},
  NOW(), NOW()
)
RETURNING id, identifier, title, status;

-- Passo 2c: Incrementar counter (CRITICO — nunca esquecer)
UPDATE companies SET issue_counter = {{NEXT_NUM}} + 1 WHERE id = 'ebe10308-efd7-453f-86ab-13e6fe84004f';
```

**NUNCA criar issues via SQL sem identifier e issue_number.** Causa bug de duplicate key que bloqueia toda a criacao de issues no Paperclip.

Confirmar titulo e prioridade com o utilizador antes de criar. Prioridades: critical, high, medium, low.

### Nota sobre delegação hierárquica

Issues criadas pelo Board (Emanuel) são sempre atribuídas ao CEO. O CEO delega pela cadeia:
- CEO cria sub-issue ao C-Level adequado
- C-Level cria sub-issue ao Director
- Director atribui ao especialista

Quando routines disparam, geram issues ao CEO que segue o mesmo fluxo. A cadeia está na descrição da routine (campo `description` começa com `CADEIA: CEO → ...`).

## Semântica de estados (referência rápida)

Ao criar, alterar ou interpretar estados de issues:

- **`todo`** — não iniciada, aguarda pickup
- **`in_progress`** — trabalho em curso, **incluindo aguardar sub-tasks delegadas**
- **`blocked`** — APENAS impedimento real (agente em erro, falta de permissão, dependência externa, aguarda decisão humana)
- **`done`** — concluída com resultado verificado
- **`cancelled`** — abandonada por decisão superior

**Regra INC-07:** `blocked` ≠ "delegué e estou à espera". Aguardar sub-task activa = `in_progress`. Se ao listar issues vires `blocked` sem impedimento real, alertar o utilizador.

## Modo ver (com ID ou titulo parcial)

```sql
SELECT i.*, a.name as assignee
FROM issues i LEFT JOIN agents a ON i.assignee_agent_id = a.id
WHERE i.company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
AND (i.id::text LIKE '%{{ARG}}%' OR LOWER(i.title) LIKE LOWER('%{{ARG}}%'));
```

Comentarios:
```sql
SELECT ic.body, ic.created_at, a.name as author
FROM issue_comments ic
LEFT JOIN agents a ON ic.author_agent_id = a.id
WHERE ic.issue_id = '{{ISSUE_ID}}'
ORDER BY ic.created_at ASC;
```

## Modo comentar

```sql
INSERT INTO issue_comments (id, company_id, issue_id, author_user_id, body, created_at, updated_at)
VALUES (gen_random_uuid(), 'ebe10308-efd7-453f-86ab-13e6fe84004f', '{{ISSUE_ID}}', 'v1N5OccPn9DGq6iog7qW9nEvnXYFT3iO', '{{COMENTARIO}}', NOW(), NOW())
RETURNING id;
```

Nota: `author_user_id = 'v1N5OccPn9DGq6iog7qW9nEvnXYFT3iO'` (Emanuel) → comentário aparece como Board/humano no dashboard. Nunca usar `'board'` — não é um user_id válido.

## Modo checkout / release

Checkout reserva a issue para trabalho activo (sinaliza ao Paperclip que está em curso).
Release liberta a issue de volta a `todo`.

**Checkout via API:**
```bash
curl -s -X POST "http://localhost:3100/api/issues/{{ISSUE_ID}}/checkout" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agentId": "{{AGENT_ID}}"}'
```

**Release via API:**
```bash
curl -s -X POST "http://localhost:3100/api/issues/{{ISSUE_ID}}/release" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**Fallback via BD (se API falhar):**
```sql
-- Checkout manual
UPDATE issues SET status = 'in_progress', updated_at = NOW()
WHERE id = '{{ISSUE_ID}}'
AND company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
RETURNING identifier, title, status;

-- Release manual
UPDATE issues SET status = 'todo', updated_at = NOW()
WHERE id = '{{ISSUE_ID}}'
AND company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
RETURNING identifier, title, status;
```

**Nota:** O par checkout/release é importante para o pipeline do Paperclip — evita que dois agentes peguem na mesma issue em simultâneo.

## Formato de output

Adaptar ao modo. Para lista:
```
## Issues Clip — [data]

| # | Titulo | Status | Prioridade | Assignee |
...

Total: N abertas (N critical, N high, N medium, N low)
```

---

## Healing Log

Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.

```jsonl
{"date":"2026-04-07","issue":"author_user_id = 'board' em comentários — não é user_id válido, comentário não aparecia no dashboard","fix":"Usar 'v1N5OccPn9DGq6iog7qW9nEvnXYFT3iO' (ID real de Emanuel no Paperclip)","source":"auto"}
```

*Adicionar nova linha após cada erro corrigido.*