/doc

Régénération de la documentation utilisateur du repo. Le skill délègue à l'agent doc-writer qui réécrit docs/features.md, docs/architecture.md, et docs/parcours-utilisateurs.md à partir de l'état courant du code.

Le skill est l'entrée humaine ; l'entrée orchestrée (en fin d'epic) passe par scripts/orchestration/run_doc_writer.sh invoqué directement depuis epic_loop.sh.

Mode d'invocation	Comportement
/doc sans argument	Tourne sur la branche courante. Compare HEAD vs origin/alpha. Commit local seulement — l'humain pousse lui-même.
/doc <issue#>	Tourne sur la branche d'un ticket / epic. Si <issue#> est un epic, opère sur origin/epic/<N>. Sinon opère sur la branche linkée à l'issue (sidebar Development). Commit + push automatique.

---

Step 0 — Pré-conditions

Refuser si :

• Le working tree est dirty (git status --porcelain non-vide) → demander à l'humain de commit/stash d'abord
• La branche courante est alpha ou master directement → la doc est régénérée sur les branches feature, pas sur la branche stable

if [ -n "$(git status --porcelain)" ]; then
    echo "Working tree dirty — commit ou stash d'abord."
    exit 1
fi

CURRENT=$(git branch --show-current)
if [ "$CURRENT" = "alpha" ] || [ "$CURRENT" = "master" ]; then
    echo "Refus : /doc ne tourne pas directement sur $CURRENT. Crée une branche dédiée."
    exit 1
fi

---

Step 1 — Résoudre la branche cible

Sans argument

Branche cible = branche courante. Base de comparaison = origin/alpha.

git fetch origin alpha --quiet
TARGET_BRANCH=$(git branch --show-current)
BASE_BRANCH=alpha
EPIC_N=null
PUSH_AUTO=false  # commit local, l'humain push lui-même

Avec un argument <issue#>

ISSUE_N="${ARGUMENTS%% *}"; ISSUE_N="${ISSUE_N#\#}"

ISSUE_TYPE=$(gh issue view "$ISSUE_N" --json issueType --jq '.issueType.name')

if [ "$ISSUE_TYPE" = "Feature" ]; then
    # Epic → tourne sur la branche d'intégration
    TARGET_BRANCH="epic/$ISSUE_N"
    BASE_BRANCH=alpha
    EPIC_N="$ISSUE_N"
else
    # Task / Bug → trouver la branche linkée à l'issue
    TARGET_BRANCH=$(gh api graphql -f query='
        query($owner:String!, $repo:String!, $n:Int!) {
          repository(owner:$owner, name:$repo) {
            issue(number:$n) {
              linkedBranches(first:5) { nodes { ref { name } } }
            }
          }
        }' -f owner=SocialGouv -f repo=egapro -F n=$ISSUE_N \
        --jq '.data.repository.issue.linkedBranches.nodes[0].ref.name // empty')

    if [ -z "$TARGET_BRANCH" ]; then
        echo "Aucune branche linkée à l'issue #$ISSUE_N."
        exit 1
    fi

    # Base = parent epic si l'issue est sub-issue d'un epic, sinon alpha
    PARENT=$(gh api graphql -f query='...parent...' --jq '.parent.number // empty')
    if [ -n "$PARENT" ]; then
        BASE_BRANCH="epic/$PARENT"
    else
        BASE_BRANCH=alpha
    fi
    EPIC_N="${PARENT:-null}"
fi

PUSH_AUTO=true
git fetch origin "$TARGET_BRANCH" "$BASE_BRANCH" --quiet
git checkout "$TARGET_BRANCH"
git pull --ff-only origin "$TARGET_BRANCH"

---

Step 2 — Invoquer l'agent doc-writer

Inputs à passer à l'agent (via le prompt de subagent) :

• epic : $EPIC_N (ou null)
• branch : $TARGET_BRANCH
• base_branch : $BASE_BRANCH
• mode : pipeline si PUSH_AUTO=true, skill sinon
• worktree : . (skill = repo courant ; pas de worktree dédié)

L'agent suit .claude/agents/doc-writer/AGENT.md :

1. Calcule le diff <base>...HEAD
2. Heuristique no-op : si rien de fonctionnel n'a changé → retour no_changes
3. Sinon : régénère from scratch les fichiers docs/*.md impactés
4. Commit
5. Push si mode=pipeline, sinon laisse le commit local

L'agent retourne un JSON strict (4 cas possibles, voir AGENT.md).

---

Step 3 — Parser le JSON retourné

.status	Action	Markdown affiché
updated	(mode skill) signaler le commit local non poussé ; (mode pipeline) signaler le push	## Doc: UPDATED + liste des fichiers + sha
no_changes	aucune	## Doc: NO_CHANGES + reason
rate_limited	proposer de retenter dans retry_in secondes	## Doc: RATE_LIMITED
failed	propager l'erreur	## Doc: FAILED + raison

Si notes est présent dans le JSON, l'afficher tel quel à l'humain (ex : "couverture insuffisante, envisager docs/api-publique.md").

En mode skill (commit local), terminer le message par :

Le commit a été créé localement. Relis le diff (`git show HEAD`) et push avec `git push` quand tu es prêt.

---

Quand utiliser /doc

• Hotfix sur alpha direct : non, refusé par Step 0.
• Branche feature standalone (sans epic) : /doc (sans arg) — utile après une grosse refacto.
• Sub-task d'un epic : /doc <ticket#> ou laisse epic_loop.sh invoquer doc-writer automatiquement à la fin de l'epic. Cumul possible mais redondant.
• Avant d'ouvrir une PR feature manuelle : /doc → relit le commit doc → push avec le reste.
• Régénération forcée : invoquer /doc <epic#> après un merge important sur alpha pour resynchroniser le wiki dans la foulée.

Quand NE PAS utiliser /doc

• Sur alpha ou master → refusé
• Quand le diff vs base est uniquement du code de tests / CI / scripts d'orchestration → l'agent retournera no_changes de toutes façons, autant ne pas le lancer
• Sur une branche en cours de travail (working tree dirty) → refusé

---

Référence

• Agent : .claude/agents/doc-writer/AGENT.md
• Script orchestration (mode pipeline) : scripts/orchestration/run_doc_writer.sh
• Workflow GitHub Action de sync wiki : .github/workflows/sync-docs-to-wiki.yaml
• Décision architecturale : voir mémoire project_doc_system