Jobo16/ielts-buddy / skills/ielts-writing-review
ielts-writing-review
Verified批改雅思 Task 1 或 Task 2 作文,进行写前规划、原文证据批注和二改对照;需要可下载 Word 时生成并验证文档。用户提供作文即可使用,网站连接可选。
references/writing-revision-loop/WORKFLOW.md
View on GitHub# Writing Revision Loop
> 当当前学习任务需要本方法时按需读取。脚本命令中的 `scripts/` 相对于本 Skill 根目录;执行时解析为安装目录中的绝对路径。
## Core Rule
The first review is not the finish line. The value is whether the learner can revise and avoid repeating the same errors.
## Inputs
Use one of:
1. Original reviewed DOCX from `ielts-task1-review` or `ielts-task2-review` plus a revised answer.
2. Original prompt, original essay, review notes, and revised essay.
3. Read-only IELTS Buddy writing record data plus a revised answer, if the record was already created elsewhere.
Do not rescore the revised essay before checking whether the original priority comments were fixed.
Do not call a server-side “fresh review” or “submit revision for feedback” tool. The revision check is local Agent work.
## Workflow
1. Read the original review's major comments, score blockers, and model answer.
2. Compare the revised answer against the original answer.
3. Mark each original issue:
- fixed;
- improved but still weak;
- unchanged;
- worsened;
- no longer relevant.
4. Identify new problems introduced by the revision.
5. Give a new band estimate only after the fix-check.
6. Create one next rewrite target, not a full new essay plan unless asked.
7. Record recurring writing errors into the learning loop.
Use the same canonical Writing codes as the first review. Record a new rubric observation only when the revision provides direct evidence; task completion alone is not evidence of improvement.
## Requested document output
When the learner requests a Word revision report, deliver a validated `.docx`; otherwise provide the comparison in conversation.
1. Build a revision plan from the original review and revised answer.
2. Generate the report with `scripts/writing-revision-loop/create_revision_report_docx.py`.
3. Validate it with `scripts/writing-revision-loop/validate_revision_report_docx.py`.
4. Return the absolute path to the final DOCX.
5. If validation fails, fix the plan and rerun generation plus validation.
For quick chat-only use, summarize with this shape:
```text
Fixed: <issues>
Still weak: <issues>
New issue: <issue>
Band movement: <old estimate -> new estimate>
Rewrite target: <one concrete instruction>
```
## Relation To Existing Workflows
Use the existing Task 1 and Task 2 review workflows for first-pass correction. This workflow starts only after the learner submits a revision.
## IELTS Buddy Data Hand-off
After the revision report is generated and validated, persist only caller-provided results when a data-only Agent API tool exists: revised answer, fixed/unchanged issue summary, local score movement, next rewrite target, and artifact metadata.
If the available Agent API revision tool says it will generate a fresh review, skip the write-back and return the local DOCX. Never overwrite the original reviewed DOCX.
## Bundled Resources
- `scripts/writing-revision-loop/create_revision_report_docx.py`: create a revision-report DOCX from a JSON plan. It includes a fix-check table, score movement, new issues, revised answer, next rewrite target, and micro-drills.
- `scripts/writing-revision-loop/validate_revision_report_docx.py`: verify required sections, tables, page breaks, Times New Roman, and plan content.
## JSON Revision Plan For DOCX Creation
Create a JSON file with this shape:
```json
{
"task_type": "Task 2",
"prompt": "Task prompt",
"original_band": "6.5",
"revised_band": "7.0",
"overall_judgement": "The revision fixes the main task-response issue but still needs tighter paragraph progression.",
"fix_checks": [
{
"issue": "The original introduction did not state a clear position.",
"status": "fixed",
"evidence": "The revised introduction now says ...",
"comment": "Clearer and more examiner-friendly."
},
{
"issue": "Body paragraph 2 used vague support.",
"status": "improved",
"evidence": "The example is more specific, but the explanation stops early.",
"comment": "Extend the consequence by one sentence."
}
],
"criterion_scores": {
"Task Response": {"before": "6.5", "after": "7", "note": "Position and support are clearer."},
"Coherence & Cohesion": {"before": "6.5", "after": "6.5", "note": "Progression still needs work."},
"Lexical Resource": {"before": "7", "after": "7", "note": "Mostly stable."},
"Grammatical Range & Accuracy": {"before": "6.5", "after": "6.5", "note": "Some article and clause errors remain."},
"Overall": {"before": "6.5", "after": "7", "note": "Borderline improvement."}
},
"new_issues": [
{"issue": "New repetition", "evidence": "important ... important", "fix": "Replace the second use with a precise synonym."}
],
"revised_essay": ["Paragraph 1", "Paragraph 2", "Paragraph 3", "Paragraph 4"],
"next_rewrite_target": "Rewrite body paragraph 2 with one concrete example and one consequence sentence.",
"micro_drills": ["Write three consequence sentences using therefore / this means / as a result."]
}
```
Then run:
```bash
python scripts/writing-revision-loop/create_revision_report_docx.py revision_plan.json --source-docx "MyEssay(reviewed).docx"
python scripts/writing-revision-loop/validate_revision_report_docx.py "MyEssay(revision-report).docx" --plan-json revision_plan.json
```
For pasted text only, omit `--source-docx`; the script writes to the Desktop by default.
## Quality Bar
- Check old comments before giving a new score.
- Do not praise a revision for adding length if it fails to fix the original issue.
- Separate fixed, improved, unchanged, worsened, and new issues.
- The DOCX must contain a compact fix-check table and a single concrete next rewrite target.
- Do not overwrite the original reviewed DOCX.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |