doc

/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"