#169 Tutorial skill by isolomatov-gd · Pull Request #308 · griddynamics/rosetta · GitHub

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).

Gamified /tutorial skill that simulates init-workspace-flow, coding-agents-prompting-flow, and aqa-flow via scripted checkpoints requiring a typed reply before revealing feedback, with zero real execution or repo mutation. Registered in docs/definitions/skills.md; plugins regenerated via rosettify-plugins.

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

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.
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.
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.

…e init flow

…he last changes in the tutorial skill file

…orial-skill Co-authored-by: Cursor <cursoragent@cursor.com>

…e instead of a Q&A quiz

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

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

Rosetta Triage Review

Summary: This PR adds a user-invoked, read-only tutorial skill and generated plugin copies. The intent is clear, but the canonical source, generated output, and flow contracts are not consistent.

Findings:

High — Canonical source and shipped plugins implement different tutorials. instructions/r3/core/skills/tutorial/SKILL.md defines a real-project, stop-by-stop simulation, while README.md and all generated plugin copies define a made-up 3–5 decision-task game. A normal plugin regeneration will replace the shipped behavior with the conflicting source behavior. tut-coding.md has the same drift: its source is a six-stop simulation, while generated copies and the README require Scenario/Task/Rubric tasks.
High — The selected flows cannot be simulated by the stated common contract. The tutorial requires every stop to use a verbatim approval sentence, but UI/API execution gates require execution evidence, and testgen requires an edited questions file rather than a chat approval. Five of six referenced sets are quiz rubrics, not the promised stop-by-stop simulation contracts. The coding set also teaches mandatory gates that apply only to some request sizes.
High — The tutorial points to a non-runtime flow shape in plugin mode. It uses READ FLOW <selected>.md, but plugin mode supplies each workflow as skills/*-flow/SKILL.md; the stated sole source of truth may therefore not load in a target plugin session.
Medium — READ SKILL FILE is incomplete. The tutorial gives no required resource subpath, so it has no valid alias invocation for the selected calibration file.
Medium — The testgen and API lessons reject supported flow inputs. They make gain.json/backend code mandatory where the underlying flows support ticket-plus-URL configuration and OpenAPI/documented sources; they also reject supported pass/fail execution evidence.

Caveats:

Static analysis and CodeQL checks pass. The validation workflow was pending when triage ran.

Suggestions:

Choose one tutorial model as the canonical source, align the README and all reference sets to it, then regenerate plugins.
Define a validated adapter per selectable flow: its actual stops, artifact shape, gate type, and accepted learner response. Do not apply approval-token rules to file- or execution-evidence gates.
Add source-to-plugin parity validation so generated copies cannot drift from the canonical skill.

Automated triage by Rosetta agent

Rosetta Triage Review

Summary: This PR adds a tutorial skill and generated plugin artifacts. The source skill is a real-project, stop-by-stop simulation, but the published plugin copies implement an older quiz flow.

Findings:

High — generated artifacts are stale. The source requires a learner's real task and repository artifacts, while shipped copies in plugins/** still teach a made-up scenario with 3–5 quiz tasks. Regenerate and verify all plugin targets after final source changes; otherwise installed users receive different behavior.
High — the coding tutorial moves required material past the design gate. coding-flow requires specs, plan, and review findings before design approval, but tut-coding.md presents only architecture options at that stop and places specs/plan at the next stop. This teaches approval of an incomplete Phase 3 artifact.
High — several simulated gates cannot satisfy the tutorial's exact-approval contract. The tutorial reads only the selected root flow and forbids real phase execution, but API-flow approval tokens are specified in phase files rather than the root workflow. It must explicitly load the needed teaching source or stop requiring verbatim approval text.
High — the claimed whole-session read-only lock conflicts with bootstrap precedence. The skill says NO OVERRIDE, but an explicit user instruction has higher priority than a skill. An off-topic request to edit a file creates conflicting instructions, so the safety boundary is not enforceable as written.

Caveats:

The source README.md still documents the older made-up-scenario / decision-task model. It must be synchronized with the source skill, and regeneration must propagate it.
Automated security checks were consulted. CodeQL passed; validation is still pending.

Suggestions:

Resolve the source contracts first, then regenerate plugin artifacts and add a deterministic source-to-plugin parity check that covers the skill's simulation mode, resource shapes, and README claims.

Automated triage by Rosetta agent

📋 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/README.md: 1 issue(s)
instructions/r3/core/skills/tutorial/SKILL.md: 4 issue(s)
instructions/r3/core/skills/tutorial/references/tut-api-aqa.md: 1 issue(s)
instructions/r3/core/skills/tutorial/references/tut-coding.md: 2 issue(s)
instructions/r3/core/skills/tutorial/references/tut-init-workspace.md: 1 issue(s)

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

⚠️ Issues Found

Severity	Gate	Details
High	Structural Coherence	Problem: The added README defines the tutorial as a "made-up scenario" with "3-5 decision tasks", but the added runtime SKILL.md requires "a real task from this repo" and runs the selected flow "stop to stop". The direct coding calibration file has six stops. Reason: The README is the maintainer contract required by the skill schema. Its current description can lead a maintainer to replace real-project, gate-complete simulation with a shorter fictional quiz. Solution: Align the README with the runtime contract: describe a read-only simulation grounded in the learner's real repository and distinguish flow stops from calibration tasks without fixing the count at 3-5.

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

⚠️ Issues Found

Severity	Gate	Details
Very High	Conflict Resolution	Problem: The <simulation_design> section requires waiting for an approval sentence verbatim. API-AQA requires explicit approval without exact text, while init, AQA, and testgen interactions may define no exact sentence in the loaded parent flow. Reason: The tutorial can reject valid approval or invent a sentence that the real flow does not require. Solution: Require exact text only when the flow explicitly requires it. Otherwise apply the flow's actual approval, selection, or question semantics, and allow direct phase references when the parent flow delegates the gate.
Very High	Workflow Completeness	Problem: The resources section says every reference contains per-stop narration, artifact, defect, approval, and reply data, and the process runs stop to stop. Every reference except tut-coding.md is instead a Scenario/Task/Rubric quiz set. Init and AQA flows also contain user interactions with no approval sentence. Reason: The executor must invent missing stop data or violate the rule Simulation, not quiz. Solution: Either convert every resource to the declared stop contract with distinct approval, selection, question, and report stop types, or explicitly change the process to a quiz model.
Very High	Decision Branching	Problem: Process step 2 accepts any named flow, and process step 4 reads only that selection. Unsupported named flows have no matching resource. The advertised aqa-flow is only a router, but the skill has no branch to read and simulate its routed target flow. Reason: Unsupported selections and the AQA router have no defined continuation. Solution: Validate named selections against the supported resources. For aqa-flow, simulate routing first, then read and simulate the target flow selected by the learner.
High	Self-Validation	Problem: The checklist requires end git status to match the start, but the process never captures the starting state. Reason: The no-write guarantee cannot be proved without the starting evidence. Solution: Capture the workspace baseline before repository access and define a non-Git fallback.

📄 instructions/r3/core/skills/tutorial/references/tut-api-aqa.md

⚠️ Issues Found

Severity	Gate	Details
High	Conflict Resolution	Problem: The result rubric says only runner output or a report path is accepted and that "the gate won't take your word". The direct API-AQA flow permits actual execution results as output, report path, or pass/fail. Reason: The tutorial teaches a stricter and incorrect execution-results handoff. Solution: Align the rubric with all result forms allowed by the flow, while still requiring detailed output or a report when failure triage needs it.

📄 instructions/r3/core/skills/tutorial/references/tut-coding.md

⚠️ Issues Found

Severity	Gate	Details
High	Workflow Completeness	Problem: The script always runs discovery and separate design and plan approval stops. The direct coding flow makes discovery conditional and combines the design and plan checkpoint for SMALL work. Reason: A learner can practice gates that the real flow will not present or miss the combined checkpoint that it will present. Solution: Branch on request clarity and size: skip discovery when it does not apply, and model the combined SMALL checkpoint with the approval required by the flow.
High	Reference Integrity	Problem: Stop 1 says that without naming /coding-flow, "a flow sometimes kicks in, not reliably". Rosetta's direct architecture contract says a plain request takes the lean path, /rosetta performs classification, and /<workflow> invokes that workflow directly. Reason: The current lesson teaches an unsupported routing behavior, so a learner may omit the workflow invocation and wrongly expect the coding-flow approval gates. Solution: Change the stop-1 rubric to state that explicit /coding-flow invocation selects this workflow and its gates; do not imply that the same flow may activate from a plain request.

📄 instructions/r3/core/skills/tutorial/references/tut-init-workspace.md

⚠️ Issues Found

Severity	Gate	Details
High	Precision & Explicitness	Problem: Sample task 2 calls the IDE/coding-agent answer "unskippable". The direct init-workspace-flow-context.md dependency says "All fields optional" and instructs the agent to leave placeholders for skipped fields, including unresolved gain.json inputs. Reason: The current rubric can mark a behavior wrong even though the governing phase permits it, so the learner receives incorrect feedback about a real workflow decision. Solution: Teach that the flow must ask for the IDE selection because it affects setup, while preserving the phase's explicit option to skip and leave a placeholder for later completion.

isolomatov-gd requested review from YevheniiaLementova and omaiesh as code owners August 18, 2026 17:48

isolomatov-gd mentioned this pull request Aug 18, 2026

Tutorial skill #169

Open

YevheniiaLementova reviewed Aug 19, 2026

View reviewed changes