# Routine Narratives — Playbook

Long-running job: write a business-context narrative for every procedure
(1,687) and function (177) page in `en/docs/auto-catalog/{procedures,functions}/`,
replacing the auto-generated `_No human-written narrative yet._` placeholder
under each page's `## Narrative` heading.

Goal: a maintainer reading the page learns **what business action this routine
serves**, not just what its parameter list is. The file:line citations live in
`reference/maintainer/`; routine narratives stay business-first.

---

## Narrative shape (≤ ~15 lines per routine)

```
**Business context:** [module path from gdsmodule.sChinese — leaf → root,
" → " separated] — [one sentence: what user action / business outcome
triggers this]

**What it does:** [terse mechanism, 1-3 sentences]

**Invocation:** [how it's reached — form-master sSqlStr, gdsmodule hook,
chained from another proc, JMS CHANGE_GDS_MODULE path, or "no callers
found (candidate dead code)"]

[Caveats / bugs / edge cases — only when worth flagging]
```

Three already-written samples for reference:
- `en/docs/auto-catalog/functions/Fn_find_modleAllId.md`
- `en/docs/auto-catalog/procedures/sp_get_sOppositeColor.md` (orphan example)
- `en/docs/auto-catalog/procedures/PRO_ERPMERGEBASESISWORKCENTER.md` (denorm-merge family)

---

## Lookup recipe (per routine)

```bash
ROUTINE="<name>"

# 1. Body
mysql --defaults-file=~/.my.cnf xlyweberp_saas_ai \
  -e "SHOW CREATE {PROCEDURE|FUNCTION} $ROUTINE"

# 2. Business-module location — form embeds (procs primarily)
mysql --defaults-file=~/.my.cnf xlyweberp_saas_ai -e "
  SELECT gfm.sId AS form_sId, m.sId AS module_sId, m.sChinese, m.sParentId
  FROM gdsconfigformmaster gfm
  LEFT JOIN gdsmodule m ON gfm.sParentId = m.sId
  WHERE gfm.sSqlStr      LIKE '%$ROUTINE%'
     OR gfm.sConfigSqlStr LIKE '%$ROUTINE%'
     OR gfm.sSqlCondition LIKE '%$ROUTINE%'"

# 3. Business-module location — module hooks (procs only)
mysql --defaults-file=~/.my.cnf xlyweberp_saas_ai -e "
  SELECT sId, sChinese, sParentId,
         sSaveProName, sSaveProNameBefore, sDeleteProName, sProcName
  FROM gdsmodule
  WHERE sSaveProName       = '$ROUTINE'
     OR sSaveProNameBefore = '$ROUTINE'
     OR sDeleteProName     = '$ROUTINE'
     OR sProcName          = '$ROUTINE'"

# 4. Climb the module tree for any sId found in #2 or #3 (replace MID)
mysql --defaults-file=~/.my.cnf xlyweberp_saas_ai -e "
  SELECT 1 d, sId, sChinese, sParentId FROM gdsmodule WHERE sId='MID'
  UNION SELECT 2, sId, sChinese, sParentId FROM gdsmodule
        WHERE sId=(SELECT sParentId FROM gdsmodule WHERE sId='MID')
  UNION SELECT 3, m3.sId, m3.sChinese, m3.sParentId
        FROM gdsmodule m3
        JOIN gdsmodule m2 ON m3.sId = m2.sParentId
        JOIN gdsmodule m1 ON m2.sId = m1.sParentId
        WHERE m1.sId = 'MID'
  ORDER BY d"

# 5. Other-routine callers (procs that CALL it, funcs that reference it)
mysql --defaults-file=~/.my.cnf xlyweberp_saas_ai -sNe "
  SELECT ROUTINE_TYPE, ROUTINE_NAME
  FROM information_schema.ROUTINES
  WHERE ROUTINE_SCHEMA = 'xlyweberp_saas_ai'
    AND ROUTINE_NAME != '$ROUTINE'
    AND ROUTINE_DEFINITION LIKE '%$ROUTINE%'"

# 6. Java / MyBatis XML / SQL-template refs
grep -rln "$ROUTINE" /Users/reporkey/Desktop/revs_engi_wiki/xly-src \
  --include="*.java" --include="*.xml" --include="*.sql" 2>/dev/null
```

**Orphan rule:** if #2 + #3 + #5 + #6 are all empty, the routine has no
discoverable caller. Flag in the narrative as `Status: appears orphaned. No
caller found in any channel — candidate for maintainer audit.`

**`sSaveProName`/`sSaveProNameBefore`/`sDeleteProName`/`sProcName` live on
`gdsmodule`**, not on `gdsconfigformmaster`. The auto-catalog page text and
older wiki drafts sometimes confuse this — trust the queries above.

---

## Style rules

- **Keep Chinese module names in Chinese.** `sChinese` is what the user sees
  in BACK. Don't translate `工作中心`, `选择工序(轮转)`, etc. — translating
  breaks searchability against the live UI.
- **Use the three headings literally:** `**Business context:**`,
  `**What it does:**`, `**Invocation:**`. Consistent shape aids scanning.
- **1–3 sentences per section. ≤15 lines total.** If the body is small and
  self-explanatory, the narrative can be shorter. Don't pad.
- **No file:line citations to xly-src** in routine narratives. Those belong
  in `reference/maintainer/`. Exception: if the routine is uniquely tied to
  a single Java caller, name the class (not the line).
- **Cross-link only when load-bearing.** Relative paths:
  `../../slices/...`, `../../reference/maintainer/...`,
  `../procedures/<other>.md`, `../functions/<other>.md`. Test that the
  target exists before adding the link.
- **Don't translate identifiers** — proc/function/column/table names stay as
  written.
- **Don't editorialize** ("interestingly", "it's worth noting") — state
  directly.
- **Don't claim Java callers without grepping.** The lookup recipe's step 6
  is the ground truth.

---

## Resume protocol — what counts as "done"

A routine is **done** when its `.md` file's `## Narrative` block contains
anything other than `_No human-written narrative yet._`.

To get the live pending count and next batch:

```bash
cd /Users/reporkey/Desktop/revs_engi_wiki/xly-wiki

# Pending count
grep -l "_No human-written narrative yet._" \
  en/docs/auto-catalog/procedures/*.md \
  en/docs/auto-catalog/functions/*.md | wc -l

# Next 20 pending (alphabetical)
grep -l "_No human-written narrative yet._" \
  en/docs/auto-catalog/procedures/*.md \
  en/docs/auto-catalog/functions/*.md | sort | head -20
```

---

## Persistence — `gen_catalog.py` is patched

Both `en/scripts/gen_catalog.py` and `zh/scripts/gen_catalog.py` now
snapshot the `## Narrative` (en) / `## 说明` (zh) block before the
`shutil.rmtree`, and re-inject preserved content during the regen. So
re-running the generator does **not** wipe human prose. Safe to regen
at any time.

zh translation is a follow-up pass after en is complete. For now, write
English narratives only.

---

## Subagent prompt template

When the user says "continue", spawn ONE subagent with this prompt:

```
Read /Users/reporkey/Desktop/revs_engi_wiki/xly-wiki/en/scripts/narrate_routines.md
in full. It contains the goal, narrative shape, lookup recipe, style rules,
and resume protocol for adding business-context narratives to xly's stored
procedures and functions.

Identify the next N pending routines using the resume-protocol command in the
playbook. N = 20 (or fewer if the routines are large/complex — judge from the
ROUTINE_DEFINITION size: large bodies take longer to read; aim for ≤90 minutes
of work).

For each routine, in alphabetical order:

1. Run the Lookup recipe end-to-end. Capture findings.
2. Write the narrative in the shape the playbook specifies — three labelled
   sections, business-first, Chinese module names preserved.
3. Edit the .md file: replace `_No human-written narrative yet._` with the
   narrative prose. Leave the `## Narrative` heading and surrounding blanks
   intact.

Don't dispatch sub-subagents. Don't rebuild the site. Don't run gen_catalog.py.
Don't translate anything to Chinese.

When done with the batch:
- List the routine names processed, one per line.
- Run the resume-protocol command and print the new pending count.
- Note any orphans found (status: "no callers found") so the user can audit.
- Append a row to the Progress log table in narrate_routines.md.
```

---

## Progress log

| Date | Procedures done | Functions done | Pending | Notes |
|---|---:|---:|---:|---|
| 2026-05-11 | 2 | 1 | 1861 | Initial 3 samples + gen_catalog.py preservation patch (en + zh) |