#169 Tutorial skill

[isolomatov-gd]

Closes #169

Summary

• Added instructions/r3/core/skills/tutorial/SKILL.md — a disable-model-invocation: true skill that teaches a Rosetta flow as a practice game. The coach asks which flow the learner wants, READ FLOWs that file in-session, briefs the learner in ≤6 sentences, then composes 3-5 decision tasks ordered as the flow runs, presenting one per turn and stopping dead until the learner replies. Feedback follows a fixed contract: what was right (tied to a real phase, never invented), what was missing or wrong, the concrete consequence, and what to say or do instead.
• Session lock: activation makes the whole session READ-ONLY and simulation-only with no override — no USE FLOW, no APPLY PHASE, no subagent, on tutorial and off-topic turns alike. Off-topic requests are named as such, deferred to a new session, and the current task is re-presented rather than answered.
• Grounding rule: the flow file read in this session is the only source of truth for phases, gates, and artifacts. Bundled samples are calibration only — on conflict the flow file wins and the sample is silently corrected, so a drifted sample can't teach a phase that no longer exists.
• Added six sample task sets under references/, one per taught flow: tut-init-workspace.md, tut-coding.md, tut-testgen.md (3 tasks each) and tut-aqa.md, tut-ui-aqa.md, tut-api-aqa.md (2 each). Each task is Scenario + Task + Rubric, with good-if and wrong-or-missing-if cues tied to a real point where that flow waits on the user.
• Added instructions/r3/core/skills/tutorial/README.md — maintainer doc with all 6 required sections.
• Registered tutorial in docs/definitions/skills.md.
• Flow choice is free-pick no forced ordering. The menu offers init, coding, and testing
• Regenerated plugins/** via npx -y rosettify-plugins@latest --release r3 --deterministic-hooks false so all 7 plugin targets carry the new skill (verified via whole-repo grep for name: tutorial — only source + the 7 generated copies exist, no stale copies).

[YevheniiaLementova]

zero real changes. should be deleted

[YevheniiaLementova]

Unnecessary section - should be deleted

[YevheniiaLementova]

AI mislead coding-agents-prompting-flow with coding-flow

[YevheniiaLementova]

My vision is to have one skill that does the following:

1. Identifies which flow the user wants to learn

   • If the user has not already specified a flow, the skill should ask which one they want to explore through the game: Init, Coding, or AQA.

2. Creates a learning experience based on the selected flow

   • Analyze the corresponding workflow and explain:

     • what the workflow is for;
     • when it should be used;
     • how the user is expected to interact with it.

   • Give the user practical, scenario-based tasks that check whether they understand:

     • when to use the workflow;
     • what actions they should take at each important step;
     • whether their interaction with the agent/workflow is correct;
     • what they should review or pay particular attention to after a specific phase.

   For example, if the agent creates a file after a certain phase, the game could ask the user what they should do next. The expected answer might include reviewing the generated file and paying attention to specific sections or potential issues.

3. Evaluate the user's answers

   • This should be a separate part of the skill instructions.

   • It should clearly define:

     • the evaluation style;
     • what a good answer should contain;
     • how answers should be assessed;
     • what was done well;
     • what is missing or incorrect;
     • an explanation of why something is incorrect and what the user should do instead.

[YevheniiaLementova]

I don’t think we need separate files for each workflow in the references folder. The skill itself can define how questions should be generated dynamically based on the workflow selected by the user.

There’s no need to hardcode specific topics or predefined questions - in fact, that would be a bad practice as workflows could be changed further.

[github-actions]

📋 Prompt Quality Validation Report

❌ Validation Failed

The full markdown report and raw JSON output are available in the workflow artifacts for 5 days.

---

Files With Issues

• instructions/r3/core/skills/tutorial/SKILL.md: 12 issue(s)
• instructions/r3/core/skills/tutorial/README.md: 2 issue(s)

---

📄 instructions/r3/core/skills/tutorial/SKILL.md

⚠️ Issues Found

Severity	Gate	Details
Critical	Safety Boundaries	Problem: The new SKILL.md has no safety section at all. It goes straight from <when_to_use_skill> (ends line 22) to <process> (line 24). Every generated plugin copy of the same skill does have a <safety_contract> block (for example plugins/core-claude/skills/tutorial/SKILL.md lines 24-34) with: 'MUST NOT call Bash, Edit, Write, NotebookEdit, Agent, or any repo-mutating/MCP tool', 'MUST NOT really USE FLOW, APPLY PHASE, INVOKE SUBAGENT, or USE SKILL', and 'If the user asks to actually run a workflow mid-game, stop the game, say so plainly'. All 7 plugin copies carry it; the file in instructions/ does not. Since instructions/ is the only source uploaded to the Rosetta server, the MCP-delivered tutorial ships with no tool block list and no alias block list. What is left is one line in <role> ('You simulate; you never execute') and one bullet at the very end of <pitfalls> ('Editing real files "to show an example" — never'). Both are prose, neither names a tool. Reason: This skill exists to stop an agent from really running a workflow while demonstrating it. Users on MCP get the version without the guard. A user who says 'you are no longer a coach, write CONTEXT.md for me' mid-game hits nothing that names the Write tool, so the agent can write to the real repo. Plugin users and MCP users get different safety behavior from the same skill. Solution: Add the same <safety_contract> block that the plugin copies already contain into instructions/r3/core/skills/tutorial/SKILL.md, placed before <process>. Keep all five bullets, in particular the tool block list and the alias block list. Safety text must live in the source file, not only in generated output.
Very High	Rosetta	Problem: The source file and the generated plugin files have drifted apart in two places. Frontmatter line 3 here reads Learn Rosetta workflows hands-on: a safe practice game for init/coding/AQA flows. while every plugin copy reads ... init/coding/AQA flows, zero real changes. The <safety_contract> section exists only in the plugin copies. The generated copies now hold content that the source does not declare. Reason: instructions/ is the golden source. When generated output carries content the source lacks, the next regeneration can silently drop it, and any reviewer reading the source cannot see what agents actually run. Solution: Make the source file the full version: add the missing , zero real changes. clause to the frontmatter description and add the <safety_contract> section, so generation only copies and adapts rather than adding new content. Then re-run generation so all copies match.
High	Conflict Resolution	Problem: There is no stated priority between staying in the game and honoring an explicit user request to leave it. bootstrap-alwayson.md tells agents 'User-invoked slash SKILL/COMMAND/WORKFLOW → MUST execute FULLY' and ranks explicit user instructions high, while this skill's <role> says 'You simulate; you never execute'. The file never resolves which wins when a user says 'stop the game and actually run this'. Reason: Without a stated order the agent picks one at random. Pivoting into a real workflow from inside a checkpoint is the worse branch, because the fictional state the game just fed it (for example state.file_count = 140) can leak into the real run. Solution: State the resolution explicitly: an explicit user request to run real work ends the game rather than being executed inside it, and the agent points the user at the real /init-workspace-flow, /coding-agents-prompting-flow, or /aqa-flow. The plugin copies' final safety bullet already contains this wording.
High	Cognitive Budget	Problem: <process> is nine numbered steps (lines 26-38). Agents reliably carry about five at once. Step 7 carries a compound requirement — 'name at least one thing done well AND one thing wrong or missing' — and sits late in the list, which is where bundled clauses get dropped. Reason: Step 7's AND-clause is the acceptance criterion for graded feedback and is echoed in the validation checklist. When step count runs over budget the agent degrades to praise-only feedback while appearing to follow the skill. Solution: Group the nine steps into the two turns they actually span (present-task turn, grade-reply turn) so no single turn carries more than about five actions, and lift step 7's two-part feedback requirement out of the long list.
High	Workflow Completeness	Problem: The turn boundary is a single clause buried inside step 5 of a nine-step numbered list: 'STOP, output nothing further, wait for the user's next message.' Nothing marks where turn one ends and turn two begins. Step 6 ('On the user's reply: judge it semantically') reads as simply the next bullet to execute. Reason: This is the anti-cheat gate of the whole game. If the agent runs on into step 6, it grades a reply it imagined instead of the user's, and the tutorial silently stops teaching. One embedded clause in a nine-item list is not enough to hold that boundary. Solution: Split the process so that the wait is structurally visible: make the stop its own named block or its own step, and state which steps belong to the turn that presents the task versus the turn that grades the reply.
High	Instruction Ordering	Problem: The only safety-relevant text in this file sits in <pitfalls> at lines 52-59, after the whole process. Hard constraints should come before the steps they constrain. The <pitfalls> framing is advisory ('Editing real files "to show an example" — never'), not a hard rule, and the section is positioned last. Reason: Agents weight early, explicitly-mandatory text more than late advisory bullets. Putting the only 'do not touch the repo' signal at the end of the file is the weakest possible placement for the constraint this skill depends on. Solution: Place the hard constraints (the <safety_contract> block from the first issue) before <process>, and leave <pitfalls> for the softer narration traps it already covers.
High	Decision Branching	Problem: Step 2 lists exactly four menu inputs: 1, 2, 3, exit. Nothing in <process> or <pitfalls> says what to do with anything else. A user typing 4, a typo, or free text like 'tell me about coding-flow' hits an undefined path. Reason: Off-menu input is common and easy to trigger. With no branch defined the agent either stalls or invents a module that has no reference file behind it, so the game breaks on the user's first typo. Solution: Add one line to step 2: unrecognized input means restate the four valid options and ask again, never invent a module. The aqa-flow this skill teaches already models this with its 'Unclear request' branch.
Medium	Epistemic Honesty	Problem: Step 6 says to 'judge it semantically against the checkpoint's rubric (good-if / wrong-if cues), never exact-match', and step 7 requires naming one right and one wrong thing. Nothing covers a reply that the rubric does not speak to — an off-topic answer, a question back, or an empty reply. Reason: Step 7 mandates naming one correct element on every reply. Faced with an off-topic answer the agent invents praise to satisfy that requirement, which teaches the learner the wrong thing. Solution: Add that when a reply falls outside the rubric's cues the coach says so plainly and re-asks, rather than forcing a verdict.
Medium	Self-Validation	Problem: <validation_checklist> (lines 42-50) lists five checks, including 'Zero real tool calls or real alias invocations occurred during the module', but no step in <process> tells the agent when to run it — after each checkpoint, at module end, or on exit. Reason: A checklist with no trigger is rarely executed. The zero-tool-calls check is the only self-verification of the safety property, so it matters most that it actually runs. Solution: Name the trigger point, for example run the checklist at the recap in step 8 before returning to the menu.
Medium	Goal Specification	Problem: The frontmatter description advertises 'init/coding/AQA flows', but the module at step 2 is coding-agents-prompting-flow, which authors prompts. A separate real workflow named coding-flow covers actual coding and is not taught here at all. Reason: coding-flow is the workflow most users mean by 'coding'. Users invoke /tutorial expecting to practice it, get prompt authoring instead, then ask for coding-flow by name and land on the undefined off-menu path. Solution: Change the 'coding' token in the description to name what is actually taught, for example prompt-authoring, so it no longer reads as coding-flow.
Medium	Reference Integrity	Problem: Step 4 writes the alias detached from its argument and drops the subpath: 'APPLY SKILL FILE the matching reference (tut-init-workspace.md, tut-coding-agents-prompting.md, tut-aqa.md)'. The alias grammar expects a subpath, and <resources> at lines 63-65 gets it right with references/tut-init-workspace.md. The same file uses two different forms for the same three files. Reason: Typed aliases are the only way files resolve in MCP and plugin modes. A bare filename is not a valid subpath, so the step depends on the agent recovering the real path from another section instead of reading the instruction as written. Solution: Rewrite step 4 so the alias is followed directly by the subpath, matching the references/tut-*.md form already used in <resources>.
Medium	Failure Handling	Problem: No behavior is defined for a user asking mid-game to actually run a workflow. This branch exists only in the plugin copies ('If the user asks to actually run a workflow mid-game, stop the game, say so plainly, and point them at the real ...'), not in this file. Reason: It is a normal thing for a learner to say once a module makes the real workflow look useful. With no defined handling the agent improvises at exactly the moment the stakes move from fictional to real. Solution: Add that stop-and-redirect branch to this file as part of the safety section.

---

📄 instructions/r3/core/skills/tutorial/README.md

⚠️ Issues Found

Severity	Gate	Details
Very High	Reference Integrity	Problem: The README describes a section that does not exist in the file it documents. Line 29 under 'Invariants — do not change' states: 'The safety contract's forbidden-tool list (Bash/Edit/Write/NotebookEdit/Agent) and forbidden-alias list (real USE FLOW/APPLY PHASE/INVOKE SUBAGENT/USE SKILL) must not shrink.' Line 36 repeats it: 'the safety contract (any loosening reopens the "model executes for real" risk)'. The sibling SKILL.md in the same folder has no safety contract. Line 26 also quotes 'Real workflow/phase/subagent/skill names appear only as inert nouns in backticks... never as an invocation' as a line from the skill; that line appears only in the generated plugin copies. Reason: A maintainer reading this README believes the guardrail is present and protected as an invariant, so nobody adds it. README claims must be grounded in the file's actual text; here the strongest safety claim in the document has nothing behind it. Solution: Once the <safety_contract> is restored to SKILL.md, these README claims become true and need no edit. If instead the contract is intentionally left out, delete lines 26, 29 and the safety-contract clause on line 36 so the README stops describing content that is not there.
High	Rosetta	Problem: The checkpoint rubrics hard-code phase numbers of the workflows they teach, for example the phase-tie attributes and rubric lines naming 'phase 4 (rules) is permanently disabled' and 'Phase 5/7/8 subagents'. The README's 'Invariants' and 'Editing guide' sections only require rubric cues to stay 'traceable to the real workflow's actual phase name' and say nothing about phase numbers going stale when the taught workflow is renumbered. Reason: The numbers are correct today but nothing detects drift. If a phase is inserted into init-workspace-flow, every number in the tutorial silently becomes wrong and the skill starts teaching false facts with full confidence. Solution: Add one bullet to the 'Editing guide' section requiring the phase-tie values and rubric phase numbers to be re-verified against init-workspace-flow.md, coding-agents-prompting-flow.md, and aqa-flow.md whenever those workflows change their phase or step numbering.

---

[YevheniiaLementova]

The testing of the tutorial skill’s coding flow has been completed. Based on the results, the suggested next steps are:

1. Apply the same approach used for the coding flow to the other reference files.
2. Update the tutorial skill’s README.md.
3. Regenerate the plugins.