---
id: po-sync-story
agent: po
title: Sincronizar uma story com a ferramenta de PM (push de metadados)
inputs: [story, ferramenta (clickup|github|jira|local)]
outputs: [story refletida na ferramenta de PM, mapa de IDs atualizado]
elicit: false
modes: [interactive, yolo]
---

# Sincronizar uma story com a ferramenta de PM (push de metadados)

**Objetivo:** refletir o estado de uma story de `docs/stories/` na ferramenta de gestão de projeto
configurada (ClickUp / GitHub Issues / Jira / local), mantendo título, status, ACs e File List
consistentes nos dois lados.

**Pré-condições:**
- A story existe em `docs/stories/` e a ferramenta de PM alvo está configurada em `.nexus/`. Se não
  houver provider configurado, **pare** e reporte — não invento integração.
- A operação é de **metadados de story** (título, status, descrição, ACs, checklist). Operações de
  git remoto e gestão de repositório **não** entram aqui.

## Passos

1. **Leia a story** em `docs/stories/` e extraia os campos sincronizáveis: título, status, ACs,
   File List, prioridade, epic de origem.
2. **Identifique o provider** alvo (`clickup` | `github` | `jira` | `local`) a partir da config em
   `.nexus/`. Recupere o ID externo da story, se já sincronizada antes.
3. **Detecte divergências** entre a story local e o item remoto: o que mudou de cada lado desde a
   última sincronização (status, ACs, descrição).
4. **Aplique a sincronização local→remoto** (esta task é push de metadados): crie o item se não
   existir, ou atualize os campos divergentes no item existente. Marque os ACs como checklist na
   ferramenta quando suportado.
5. **Persista o mapa de IDs** (story local ↔ ID externo) em `.nexus/` para que o próximo
   `*sync-story` / `*pull-story` saiba a correspondência.
6. **Registre no Change Log da story** a data da sincronização e o destino.
7. **Não opere git remoto.** Mesmo aqui, eu sincronizo **metadados de story** — não faço `git push`,
   não abro PR, não mexo em MCP. Qualquer subida de código ou integração de repositório é
   **exclusiva do `@devops`**, sem exceção.

## Critério de pronto (DoD)

- [ ] Campos sincronizáveis extraídos da story
- [ ] Provider identificado e ID externo recuperado (ou item criado)
- [ ] Divergências detectadas antes de aplicar
- [ ] Metadados refletidos local→remoto (campos + checklist de ACs quando suportado)
- [ ] Mapa de IDs (local ↔ externo) persistido em `.nexus/`
- [ ] Change Log da story atualizado com data e destino da sync
- [ ] Nenhuma operação de git remoto / PR / MCP executada (delegada ao @devops)

## Falha / recuperação

- **Provider de PM não configurado** → paro e reporto; não invento credenciais nem integração.
- **Conflito de edição** (story e item remoto mudaram o mesmo campo) → não sobrescrevo cegamente;
  sinalizo o conflito e peço a decisão antes de aplicar.
- **A operação exigiu push de código / PR / configuração de MCP** → fora do meu escopo; delego ao
  @devops.
- **Falha de autenticação na ferramenta** → reporto o erro com contexto; gestão de credenciais/MCP é
  do @devops.