Slipdock - Trabalhando a partir do quadro

Trabalhando a partir do slipdock

O quadro é o plano oficial: o que fazer a seguir, e onde vai o registro do que aconteceu. O servidor documenta suas próprias convenções — leia-as primeiro, uma vez por sessão, antes de escolher ou atualizar qualquer coisa:

slipdock guide                    # markdown, de GET /api/guide

Sem a CLI nesta máquina — que é o caso mais comum, já que a CLI precisa do Elixir:

B="${SLIPDOCK_URL:-$(cat ~/.config/slipdock/url 2>/dev/null)}"   # pergunte ao usuário se nenhum dos dois estiver definido
curl -s -H "Authorization: Bearer $SLIPDOCK_TOKEN" "$B/api/guide"

O endereço do servidor vem de $SLIPDOCK_URL, senão ~/.config/slipdock/url (escrito por slipdock url ou pelo /install.sh do servidor). Se você não tiver nenhum dos dois, pergunte ao usuário pelo endereço do Slipdock deles em vez de adivinhar um — um quadro hospedado é algo como https://app.slipdock.us, um auto-hospedado tem o nome que eles usam para acessá-lo.

Passe o token se houver um ($SLIPDOCK_TOKEN, senão ~/.config/slipdock/token). O guia não precisa de token, mas com um ele termina com os quadros reais do usuário, cada lista neles, e qual lista é a lista pronta, o backlog, a de trabalho em andamento e a de trabalho concluído — que é exatamente o que você precisa para pegar algo.

O guia vence este arquivo. Ele vem do servidor em execução, então está atual: os endpoints, os vocabulários e o layout do quadro são gerados no momento da requisição. Este arquivo só diz para você buscá-lo, e o que fazer enquanto não o tem.

Encontrando algo que ninguém consegue nomear

slipdock cards <board> --search Q filtra um quadro por substring. Seus outros filtros perguntam sobre estado em vez de palavras, e são eles que respondem "o que devo pegar": --deps ready exclui qualquer coisa esperando um cartão inacabado, --no-assignee exclui o trabalho de outras pessoas, --due overdue é o que passou do prazo. Então a lista elegível é uma chamada:

slipdock cards <board> --column "To Do" --open --deps ready --no-assignee

slipdock search <words...> é diferente: ele busca por significado, em todos os quadros que o usuário pode ver, e cobre comentários e atualizações de status além dos cartões. Use-o quando o usuário descrever uma coisa em vez de nomeá-la ("o cartão sobre o problema de arredondamento de reembolso"), quando o que você quer provavelmente foi dito em um comentário em vez de um título, ou quando você não sabe em qual quadro procurar. Leia o trecho correspondente que ele imprime, depois slipdock card <id> para o cartão inteiro antes de tocá-lo.

A versão curta que será expandida

• Épicos e subcartões. Um cartão de nível superior é um épico: um resultado, contendo a prioridade, datas e discussão. O trabalho vive em seus subcartões, uma sessão cada. Itens de checklist são os passos dentro de uma tarefa. Novo trabalho que você descobrir vai sob o épico que ele serve, como um subcartão — não como um novo cartão de nível superior.
• Selecionando. Termine o que já está em andamento; depois a lista pronta (To Do), e o backlog apenas quando nada ali é elegível. Maior prioridade primeiro, posição na lista desempatando. Pule qualquer coisa concluída, arquivada, bloqueada, esperando, adiada ou atribuída a outra pessoa — --open --deps ready --no-assignee faz a maior parte dessa filtragem para você (cartões adiados já são excluídos de slipdock cards) — e qualquer substituto (↪stand-in-for:#N): ele só marca onde um cartão foi para uma sprint. Se o quadro responder PAUSED (paused no JSON), uma pessoa pausou o trabalho do runner nele: não pegue nada e pare. Quando o cartão em que você parou tiver subcartões, desça nele e trabalhe neles até concluir antes de voltar para o próximo cartão de nível superior.
• Atualizando conforme avança. Mova o cartão para "em andamento" e atribua-o a você mesmo quando começar; comente a cada decisão, surpresa ou beco sem saída; sinalize-o (blocked, review) com um comentário dizendo o que você está esperando; quando apenas uma pessoa pode dar o que você precisa, abra uma espera e pare (slipdock wait <id> "o que você precisa" [--on EMAIL] [--choice X]..., ou update_card wait; várias perguntas vão como --question Q --question Q / questions, uma cada, nunca um bloco): isso sinaliza o cartão como waiting, e respondê-lo (slipdock answer) faz o trabalho voltar a andar — ou, quando o que ele espera tem uma data, adie-o em vez disso (slipdock snooze <id> <data> --note "…"): ele sai das listas e volta no dia, no topo de sua lista; ao finalizar, defina completed: true e mova-o para a lista de concluídos. Complete um épico apenas quando seu resumo mostrar todos os subcartões concluídos.
• Trabalho verificado, onde o quadro tiver isso ativo (sua linha no guia diz verified work: ...). Escreva a barra do cartão antes de começar (slipdock edit <id> --bar "…"), e nunca tente alterá-la depois que o trabalho começou. Complete-o com o que você verificou (slipdock done <id> --evidence-commit <sha> --tests a,b --suite passed:38:0 --evidence "…"). Em um quadro onde um segundo agente verifica, done submete o cartão e o deixa pendente: não o mova para Concluído você mesmo. Um cartão rejeitado volta com sua razão no comentário, o prompt do job e o rejection de get_card (a transferência diz Rework: ...): leia essa razão primeiro, já que ela é o próximo briefing. Verificar o cartão de outra pessoa (nunca o seu próprio) significa verificar o commit da evidência em uma árvore limpa, executar a suite (em um quadro de pull request, verificando que o CI passou naquele commit), julgá-lo contra a barra, então slipdock accept <id> ou slipdock reject <id> --reason "…". Em um quadro que entrega por pull request (a linha do quadro diz isso, assim como o prompt do job reivindicado e slipdock card), nunca faça push no branch padrão: commite em card-<id>, faça push, abra o pull request uma vez (gh pr create --head card-<id> --title "<title> (#<id>)" --fill; a próxima tentativa de um cartão rejeitado faz push no mesmo branch), monitore suas verificações (a execução completa de testes: antes de fazer push, execute apenas os testes que você adicionou ou alterou), e complete com slipdock done <id> --pr <url>. Aceitar o cartão o mescla; não o mescle você mesmo. Um merge falho envia o cartão de volta rejeitado com a razão: faça rebase do branch e submeta novamente.
• Pistas, onde elas estiverem ativas (a linha do quadro no guia diz lanes: on). Antes de iniciar um cartão, escreva os caminhos que seu trabalho tocará: slipdock edit <id> --paths "lib/foo/**,docs/manual.md", tão restrito quanto o briefing permitir. Uma movimentação recusada por sobreposição com um cartão em andamento nomeia esse cartão: restrinja os caminhos, ou deixe o cartão bloqueado por ele; apenas uma pessoa substitui uma pista. Em um quadro com push, um cartão aguardando verificação libera sua pista e seus dependentes; em um quadro com pull request, ele segura ambos até o merge. Independentemente de o quadro ter pistas ou não, em um cartão com caminhos, prepare apenas arquivos sob eles, pelo nome, e com outra sessão ativa no mesmo repositório, trabalhe em uma worktree git própria (git worktree add ../<repo>-lanes/card-<id> -b card-<id>), a menos que um runner já tenha colocado você em uma ($SLIPDOCK_WORKTREE).
• Leia a transferência primeiro, deixe uma quando parar antes do fim. A transferência de um cartão (Left off: no topo de slipdock card <id>; handoff em seu JSON) é onde quem o teve por último o deixou: o próximo passo e uma breve nota. Leia antes dos comentários quando pegar um cartão. Sempre que parar com um cartão inacabado — fim de sessão, devolvido, bloqueado, sem tempo — deixe uma: slipdock handoff <id> --next "<o único próximo passo>" --body "Estado: … Armadilhas: … Em aberto: … Apontamentos: …" (no MCP, leave_handoff). Ela substitui a última; o histórico é mantido. Comentários continuam sendo o registro contínuo; a transferência é o agora. Em um cartão finalizado, a transferência é para a pessoa: o que ela deve fazer, verificar ou saber (um deploy, uma reinstalação, uma pergunta, uma ressalva) como --next, com onde as coisas estão em alguns tópicos. Se nada foi deixado para ela: deixe em branco, e slipdock handoff <id> --clear uma deixada anteriormente.
• Releia o cartão antes de fazer push, e seus comentários depois. Depois que o trabalho estiver verificado, slipdock card <id> novamente: uma descrição alterada ou um comentário mais novo que sua reivindicação ainda é este cartão — faça isso antes de commitar. Depois que o build tiver começado, leia os comentários mais uma vez para qualquer coisa adicionada entretanto.
• Incidentes e deploys. Quando o quadro registra deploys (slipdock dora <board> responde em vez de dizer que as métricas de entrega estão desligadas), uma interrupção ou um release quebrado é um cartão comum marcado como incident; se você souber o deploy que o causou, slipdock incident-of <card> <deploy-id>. Nomeie o cartão no commit da correção (#57), como com qualquer cartão: é assim que seu deploy é contado como uma correção e o cartão recebe sua linha Shipped. Nunca registre ou finalize deploys manualmente — isso é função do CI, com seu próprio token.
• Sugestões de arrumação são para a pessoa decidir. slipdock garden <board> (no MCP, garden) lista o que o jardineiro do quadro encontrou: épicos concluídos mas abertos, cartões travados em andamento, duplicatas, páginas órfãs. Mostre-as quando pedirem para arrumar, e aplique (slipdock garden apply <id>, garden_decide) apenas o que a pessoa aprovar; trabalhando sem supervisão, nunca aplique ou descarte uma — uma descarte é lembrado.
• Trabalho de longa duração recebe atualizações intermediárias. Se a tarefa levar mais do que uma sessão curta, comente em cada marco enquanto ainda estiver em execução — o que foi entregue, o que falta, qualquer coisa que mudou o plano — e mova percent_complete junto. Um único resumo no final é tarde demais para ser útil: um cartão em andamento sem nada mais recente do que a movimentação parece abandonado. Um épico em várias sessões recebe o mesmo tratamento, uma linha a cada fechamento de subcartão.
• Comentários são Markdown, e são lidos superficialmente. Abra com uma linha em negrito dizendo o que é (**Peguei.**, **Construído.**, **Decisão:** …), depois tópicos curtos, um fato cada, com caminhos, comandos e ids de commit entre crases; nunca um parágrafo denso de cláusulas. Envie qualquer coisa com mais de uma linha com slipdock comment <id> --body - <<'EOF' … EOF (entre aspas, para que as crases sobrevivam); palavras na linha de comando perdem suas quebras de linha.
• Commit, e vincule-o. Quando o projeto for um repositório git, comite o trabalho do cartão assim que estiver completo — antes de fechar o cartão — com o id do cartão (#42) na mensagem de commit. O comentário de fechamento vincula ao commit, ou ao PR se um foi aberto (Commit: https://github.com/…/commit/abc1234). Sem remote para vincular, dê o hash curto e o branch.
• Custo de tokens no resumo. O comentário de fechamento de um cartão termina com uma linha dando os tokens que o trabalho usou, ex.: Token cost: ~135k tokens (context budget 15.00M → 14.86M, claim to close). Faça uma leitura do contador de tokens restantes (total_tokens left em mensagens de sistema) quando reivindicar o cartão e novamente quando fechá-lo, e dê a diferença. Se vários cartões foram trabalhados em uma só sequência, meça cada um a partir de sua própria reivindicação. Se nenhum contador estiver visível, diga "Token cost: not measured" em vez de estimar. Adicione o mesmo número ao comentário de progresso do épico.
• Leia os favoritos deles primeiro. slipdock favourites lista os quadros, listas, cartões e visualizações salvas que esta pessoa marcou — onde eles realmente trabalham, o que uma lista de quadros não te diz. Quando "no que devo trabalhar a seguir?" for perguntado sem nomear um quadro, um favorito é a pista mais forte que você tem. Eles são pessoais: nunca adicione ou remova um a menos que seja solicitado.
• Quadros arquivados são trabalhos que foram deixados de lado. slipdock boards os exclui de propósito; --all os mostra com um estado archived. Tudo neles ainda lê e escreve, mas nunca pegue trabalho de um quadro arquivado sem perguntar, e nunca coloque trabalho novo lá.
• Escreva o que o cartão não pode conter. Um quadro diz o que está sendo feito; é um mau lugar para como algo funciona, o que foi decidido e por quê, ou a forma de uma coisa. Esses vão para a wiki do quadro — slipdock page ls <board>, slipdock page read <page>, slipdock page new <board> <title...>. O teste é se será lido novamente depois que este cartão fechar: uma decisão, um runbook, uma especificação ou as descobertas de uma investigação serão, e pertencem a uma página (vinculada do comentário de fechamento do cartão pelo seu código, W-31); progresso, bloqueadores e o que aconteceu agora pertencem a um comentário no cartão. Nunca ambos — uma página que repete os comentários é uma página em que ninguém confia. Pesquise antes de escrever uma (slipdock page ls <board> --q <a coisa>): estender a página que existe é melhor do que uma quarta página sobre deploy. Passe --message em cada edição, e --base-hash em qualquer edição de uma página que você não acabou de escrever você mesmo, para que um salvamento nunca possa pousar silenciosamente em cima do de outra pessoa.
• Mantenha os títulos curtos. Um título de cartão tem no máximo 60 caracteres, uma série como <Series> <n>: <o que> (Agent supervision 5: Parked jobs), o detalhe na descrição. O título de um cartão se torna uma pasta e aparece em listas apertadas, e uma sequência de cartões que compartilham os primeiros 40 caracteres não podem ser distinguidos lá.
• Não delete cartões (arquive em vez disso), reescreva um título para corresponder ao que você realmente fez, arrume os cartões de outras pessoas, ou deixe um cartão em andamento com nenhum comentário mais novo do que a movimentação. Arquivar ou reordenar um quadro inteiro está ainda mais longe do seu escopo: apenas sob um pedido explícito, nomeando aquele quadro.

Quando isso se aplica

• "No que devo trabalhar a seguir?", "dar continuidade ao plano", "percorrer o backlog", "próxima tarefa" → busque o guia, depois selecione por suas regras e diga qual cartão você pegou e por quê.
• "Colocar este plano no quadro", "dividir isso em tarefas" → épicos com subcartões, conforme a forma do guia.
• Você já está no meio de uma tarefa que veio do quadro → o cartão é onde progresso, decisões e bloqueadores são escritos, conforme acontecem em vez de em um despejo no final.
• Você terminou algo que veio do quadro → finalize no quadro antes de reportar como concluído.