fix(skill): bound generate_scene retries per page (#1370)

This commit is contained in:
Chip Li 2026-09-04 05:50:26 -07:00 committed by GitHub
parent 9104824b41
commit 4cfc7c17a6
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 62 additions and 12 deletions

View File

@ -181,17 +181,8 @@ or `list_folder_stages` instead of keeping it alive by repetition.
## When something fails
One bad page does not end a series. If a page or a whole stage will not
generate:
- retry it once — every tool is idempotent, and an interrupted step just needs
re-issuing;
- if it still fails, note it, leave the rest of that stage intact, and move on
to the next one. Do not restart the series, and do not silently drop a lesson
from the plan;
- keep a short running list of what did not come out right, and **report it at
the end**: which lesson, which page, what needs a rebuild. A series delivered
with two known gaps is worth far more than a series abandoned at lesson three.
Page recovery follows `stage-design`; one failed page does not abort the rest of
the series.
## Finishing

View File

@ -44,7 +44,7 @@ order:
usable voice exists. Every page's content
and narration is written for the roster that exists when the page is
generated, so a roster settled late is a roster half the stage never saw.
4. **`generate_scene` once for EACH settled page, in ascending order** — one
4. **`generate_scene` for EACH settled page, in ascending order** — one
page per call, never more. Pass the page's settled `title`, `type` and
`brief` (plus `materialFacts` when the page's content comes from attached
material); no planned outline is needed. A `pbl` page is generated the same
@ -59,6 +59,25 @@ landed, when `ask_user` is waiting on the user, or when the stage is done by the
check below. Reporting what you have planned, imported or confirmed leaves the
user holding an empty deck.
## When `generate_scene` fails
Track generation attempts by `stageId + order`. Changing the title or brief,
or generating another page in between, does not reset the attempt.
- For `prompt-unavailable` or another deterministic failure, do not repeat the
same call.
- For `invalid-model-output`, change the brief without changing the settled
teaching intent, then retry once. Retry once for a clearly transient provider
failure too.
- If that retry fails, do not call `generate_scene` again for that target during
this run. Leave the page unwritten, continue with later pages in the same
stage, and name the gap when wrapping up. Do not call `ask_user` after every
failed page or silently drop the page from the settled plan.
Use `list_scenes` to reconcile persisted pages with the settled plan. A stage
with a missing page can be wrapped up after later pages are built, but it is not
done; name each gap and its latest failure instead of claiming completion.
## Narration audio follows narration text
When a page's narration is written or reworded with `patch_stage` on an

View File

@ -0,0 +1,40 @@
import { readFileSync } from 'node:fs';
import { resolve } from 'node:path';
import { describe, expect, it } from 'vitest';
const readSkill = (name: string) =>
readFileSync(resolve(process.cwd(), `skills/agent-runtime/${name}/SKILL.md`), 'utf8').replace(
/\s+/g,
' ',
);
describe('stage-design generation recovery contract', () => {
it('bounds retries per page without abandoning the stage', () => {
const skill = readSkill('stage-design');
for (const instruction of [
'`stageId + order`',
'does not reset the attempt',
'`prompt-unavailable`',
'do not repeat the same call',
'`invalid-model-output`',
'retry once',
'continue with later pages in the same stage',
'`ask_user` after every failed page',
'silently drop the page from the settled plan',
'it is not done',
]) {
expect(skill, instruction).toContain(instruction);
}
});
it('keeps the series layer delegated to stage-design', () => {
const skill = readSkill('curriculum-planner');
expect(skill).toContain(
'Page recovery follows `stage-design`; one failed page does not abort the rest of the series.',
);
expect(skill).not.toContain('`prompt-unavailable`');
expect(skill).not.toContain('`invalid-model-output`');
});
});