Build Unique and Reviewable Extra Examples in a Tagalog Learning App with Kiro Workshop

Audience: professional developers building content QA pipelines and AI-assisted educational apps
Duration: 2 hours
Primary AWS AI service: Kiro
Project output: a Kiro-guided QA pipeline that rewrites, deduplicates, validates, and exports reviewable extra examples.

Workshop Summary

This workshop helps developers improve extra examples in a Tagalog learning app through structured QA. Participants use Kiro to define example contracts, generate varied practice sentences, detect duplicates, add traceable context, export reviewer reports, and validate counts. The workflow turns loose supporting examples into unique, auditable learning assets that reviewers can inspect before publishing or extending across future lessons safely.

Workshop objective

Developers build a content QA pipeline for extra examples. The pipeline extracts the main Natural Tagalog sentence, generates three related examples, detects duplicates across the site, adds traceable context, exports reviewer reports, and validates card/example counts.

2-hour agenda

Step 1 — Create Kiro steering for extra-example QA

Developer action

1. Generate steering docs in Kiro.
2. Add extra-example QA rules.
3. Ask Kiro to list content risks.
4. Commit steering before writing scripts.

Kiro prompt sample

Create steering docs for extra-example quality. Each card must have three related examples. Examples must be unique enough for review, traceable by article and sentence number, and marked as draft until reviewed.

System design decision

1. Make Step 1 — Create Kiro steering for extra-example QA explicit before coding: Professional developers should not rely on hidden assumptions when using AI-assisted engineering. The workshop first writes the rule into steering or specs so Kiro has durable project context. This makes generated code more consistent, gives reviewers something concrete to inspect, and prevents repeated explanation in every chat. The decision also helps new developers understand why a file exists, what problem it solves, and which behavior is allowed or disallowed.
2. Keep the implementation deterministic and reviewable: Kiro can help generate code, tests, and documentation, but the workshop output should be reproducible. Deterministic scripts, explicit configuration, stable schemas, and validation reports make the result easier to debug. When every transformation has a visible input and output, developers can review diffs, rerun checks, and explain the system to another engineer. This is especially important for language-learning content where correctness and cultural context require human review.
3. Attach validation to the workflow, not only the final demo: The workshop treats validation as part of system design. Each step has a check, a report, or a hook so defects appear close to the change that caused them. This approach lets Kiro act as a coding assistant and quality reviewer while developers stay in control. The result is a practical professional workflow: plan with specs, guide with steering, implement in small tasks, validate output, and document handoff.

Code sample — .kiro/steering/extra-example-qa.md

# Extra Example QA Steering

- Every sentence card must have exactly three extra examples.
- Examples must relate to the card's Natural Tagalog sentence.
- Track article number, sentence number, and example number.
- Detect duplicate Tagalog example text across the whole site.
- Add review status and reviewer notes to every generated example.
- Fail validation if card counts or example counts are wrong.

Code explanation

• Business logic: The steering file defines extra examples as reviewable learning content.
• Code logic: Kiro uses the rules when generating specs, models, rewrite scripts, validators, hooks, and docs.
• Expected result: Future code includes traceability, duplicate detection, and review metadata.

Step 2 — Define reviewable extra-example records

Developer action

1. Create example_model.py.
2. Add review status and traceability fields.
3. Validate required text.
4. Serialize records for reports.

Kiro prompt sample

Create a Python dataclass model for reviewable extra examples. Fields: articleNumber, sentenceNumber, exampleNumber, sourceNaturalTagalog, tagalog, english, naturalTagalog, politeTagalog, duplicateGroup, reviewStatus, reviewNotes.

System design decision

1. Make Step 2 — Define reviewable extra-example records explicit before coding: Professional developers should not rely on hidden assumptions when using AI-assisted engineering. The workshop first writes the rule into steering or specs so Kiro has durable project context. This makes generated code more consistent, gives reviewers something concrete to inspect, and prevents repeated explanation in every chat. The decision also helps new developers understand why a file exists, what problem it solves, and which behavior is allowed or disallowed.
2. Keep the implementation deterministic and reviewable: Kiro can help generate code, tests, and documentation, but the workshop output should be reproducible. Deterministic scripts, explicit configuration, stable schemas, and validation reports make the result easier to debug. When every transformation has a visible input and output, developers can review diffs, rerun checks, and explain the system to another engineer. This is especially important for language-learning content where correctness and cultural context require human review.
3. Attach validation to the workflow, not only the final demo: The workshop treats validation as part of system design. Each step has a check, a report, or a hook so defects appear close to the change that caused them. This approach lets Kiro act as a coding assistant and quality reviewer while developers stay in control. The result is a practical professional workflow: plan with specs, guide with steering, implement in small tasks, validate output, and document handoff.

Code sample — example_model.py

from dataclasses import dataclass, asdict

ALLOWED_REVIEW_STATUS = {"draft", "native-reviewed", "blocked"}

@dataclass
class ExtraExample:
    articleNumber: int
    sentenceNumber: int
    exampleNumber: int
    sourceNaturalTagalog: str
    tagalog: str
    english: str
    naturalTagalog: str
    politeTagalog: str
    duplicateGroup: str | None = None
    reviewStatus: str = "draft"
    reviewNotes: str = "Needs native-speaker review."

    def validate(self):
        if self.reviewStatus not in ALLOWED_REVIEW_STATUS:
            raise ValueError(f"Invalid reviewStatus: {self.reviewStatus}")
        required = [self.sourceNaturalTagalog, self.tagalog, self.english, self.naturalTagalog, self.politeTagalog]
        if any(not value.strip() for value in required):
            raise ValueError("ExtraExample has empty required text")

    def to_dict(self):
        self.validate()
        return asdict(self)

Code explanation

• Business logic: The dataclass makes every extra example traceable and reviewable.
• Code logic: It validates required text, controls review status, and serializes to dictionaries for JSON reports.
• Expected result: Calling to_dict() returns a validated record or raises a clear validation error.

Step 3 — Generate three related examples from each card

Developer action

1. Extract the main Natural Tagalog sentence.
2. Generate examples for use, repeat, and practice.
3. Add polite variants.
4. Validate each record.

Kiro prompt sample

Create a deterministic generator that produces three examples from a card's Natural Tagalog sentence. Each example includes Tagalog, English, Natural Tagalog, Polite Tagalog, source sentence, article number, sentence number, and example number.

System design decision

1. Make Step 3 — Generate three related examples from each card explicit before coding: Professional developers should not rely on hidden assumptions when using AI-assisted engineering. The workshop first writes the rule into steering or specs so Kiro has durable project context. This makes generated code more consistent, gives reviewers something concrete to inspect, and prevents repeated explanation in every chat. The decision also helps new developers understand why a file exists, what problem it solves, and which behavior is allowed or disallowed.
2. Keep the implementation deterministic and reviewable: Kiro can help generate code, tests, and documentation, but the workshop output should be reproducible. Deterministic scripts, explicit configuration, stable schemas, and validation reports make the result easier to debug. When every transformation has a visible input and output, developers can review diffs, rerun checks, and explain the system to another engineer. This is especially important for language-learning content where correctness and cultural context require human review.
3. Attach validation to the workflow, not only the final demo: The workshop treats validation as part of system design. Each step has a check, a report, or a hook so defects appear close to the change that caused them. This approach lets Kiro act as a coding assistant and quality reviewer while developers stay in control. The result is a practical professional workflow: plan with specs, guide with steering, implement in small tasks, validate output, and document handoff.

Code sample — generate_examples.py

from example_model import ExtraExample

def generate_examples(article_number, sentence_number, natural_tagalog):
    templates = [
        (f'Gagamitin ko rin ang linyang "{natural_tagalog}" mamaya.', f'I will also use the line "{natural_tagalog}" later.', f'Uulitin ko ang linyang "{natural_tagalog}" nang dahan-dahan.', f'Pakisuyo, uulitin ko po ang linyang "{natural_tagalog}" nang dahan-dahan.'),
        (f'Sasabihin ko ang linyang "{natural_tagalog}" sa kausap ko.', f'I will say the line "{natural_tagalog}" to the person I am talking to.', f'Ipapaliwanag ko ang linyang "{natural_tagalog}" sa simpleng paraan.', f'Pakisuyo, ipapaliwanag ko po ang linyang "{natural_tagalog}" sa simpleng paraan.'),
        (f'Magsanay tayo gamit ang linyang "{natural_tagalog}" ngayon.', f'Let us practice using the line "{natural_tagalog}" now.', f'Isusulat ko ang linyang "{natural_tagalog}" sa notes ko.', f'Pakisuyo, isusulat ko po ang linyang "{natural_tagalog}" sa notes ko.')
    ]
    output = []
    for i, (tagalog, english, natural, polite) in enumerate(templates, start=1):
        example = ExtraExample(article_number, sentence_number, i, natural_tagalog, tagalog, english, natural, polite)
        example.validate()
        output.append(example)
    return output

Code explanation

• Business logic: The generator creates three reviewable examples tied to the main card sentence.
• Code logic: It fills deterministic templates, creates dataclass records, validates them, and returns structured output.
• Expected result: Calling generate_examples(4, 10, 'Paki-check kung pumasok ang bayad.') returns three draft examples with traceability.

Step 4 — Detect duplicates and export reviewer CSV

Developer action

1. Normalize Tagalog text.
2. Group duplicates across all examples.
3. Export review CSV for non-developer reviewers.
4. Ask Kiro to summarize duplicate groups.

Kiro prompt sample

Create duplicate detection and a CSV exporter. Normalize Tagalog text, group duplicates, assign duplicateGroup IDs, and output articleNumber, sentenceNumber, sourceNaturalTagalog, tagalog, english, politeTagalog, duplicateGroup, reviewStatus, and reviewNotes.

System design decision

1. Make Step 4 — Detect duplicates and export reviewer CSV explicit before coding: Professional developers should not rely on hidden assumptions when using AI-assisted engineering. The workshop first writes the rule into steering or specs so Kiro has durable project context. This makes generated code more consistent, gives reviewers something concrete to inspect, and prevents repeated explanation in every chat. The decision also helps new developers understand why a file exists, what problem it solves, and which behavior is allowed or disallowed.
2. Keep the implementation deterministic and reviewable: Kiro can help generate code, tests, and documentation, but the workshop output should be reproducible. Deterministic scripts, explicit configuration, stable schemas, and validation reports make the result easier to debug. When every transformation has a visible input and output, developers can review diffs, rerun checks, and explain the system to another engineer. This is especially important for language-learning content where correctness and cultural context require human review.
3. Attach validation to the workflow, not only the final demo: The workshop treats validation as part of system design. Each step has a check, a report, or a hook so defects appear close to the change that caused them. This approach lets Kiro act as a coding assistant and quality reviewer while developers stay in control. The result is a practical professional workflow: plan with specs, guide with steering, implement in small tasks, validate output, and document handoff.

Code sample — export_review_csv.py

import csv
import json
from pathlib import Path

COLUMNS = ["articleNumber", "sentenceNumber", "exampleNumber", "sourceNaturalTagalog", "tagalog", "english", "politeTagalog", "duplicateGroup", "reviewStatus", "reviewNotes"]

def export_csv(json_path="example-review-report.json", csv_path="example-review-report.csv"):
    payload = json.loads(Path(json_path).read_text(encoding="utf-8"))
    with open(csv_path, "w", newline="", encoding="utf-8") as file:
        writer = csv.DictWriter(file, fieldnames=COLUMNS)
        writer.writeheader()
        for example in payload["examples"]:
            writer.writerow({column: example.get(column, "") for column in COLUMNS})
    return csv_path

if __name__ == "__main__":
    print(export_csv())

Code explanation

• Business logic: The exporter makes example review accessible to non-developer reviewers through spreadsheet-compatible CSV.
• Code logic: It reads the JSON report, writes selected columns in a stable order, and returns the CSV path.
• Expected result: Running python export_review_csv.py creates example-review-report.csv for language review.

Additional Hands-on Developer Labs

These labs are unique to Workshop 6 — Unique and Reviewable Extra Examples. They extend the extra-example QA pipeline with semantic uniqueness checks, traceable example identities, rewrite queues, reviewer imports, and batch-level quality reports. The focus is example diversity and reviewability, not generic validation runners.

Hands-on Lab A — Add stable example IDs and lineage metadata

Developer action

• Ask Kiro to generate stable IDs for every extra example.
• Include article number, sentence number, example number, and source sentence hash.
• Add lineage metadata that records generation strategy and template name.
• Validate that every example ID is unique across the whole site.

Kiro prompt sample

Add stable example identity and lineage to extra examples.
Create exampleId from articleNumber, sentenceNumber, exampleNumber, and a short hash of sourceNaturalTagalog.
Add generatedBy, generationStrategy, templateName, and sourceHash fields.
Fail validation on duplicate exampleId values.

System design decision

• Review comments need stable IDs: Reviewers must be able to point to the same example after regeneration.
• Lineage explains why an example exists: A generated example should show whether it came from a practice template, context rewrite, or manual override.
• Identity supports deduplication: Duplicate detection becomes easier when every record has a stable key and source hash.

Code sample — example_identity.py

import hashlib


def short_hash(value: str) -> str:
    return hashlib.sha1(value.encode("utf-8")).hexdigest()[:8]


def example_id(article_number: int, sentence_number: int, example_number: int, source_natural_tagalog: str) -> str:
    return f"a{article_number:03d}-s{sentence_number:03d}-e{example_number:02d}-{short_hash(source_natural_tagalog)}"


def lineage(template_name: str, strategy: str = "deterministic-template") -> dict:
    return {
        "generatedBy": "workshop-6-extra-example-pipeline",
        "generationStrategy": strategy,
        "templateName": template_name
    }

Code explanation

• Business logic: Stable IDs and lineage make examples traceable through review and regeneration.
• Code logic: A short hash ties the ID to the source sentence, and lineage records the generation method.
• Expected result: Each example can be referenced in reviewer reports and deduplication logs.

Hands-on Lab B — Add semantic similarity scoring for near-duplicates

Developer action

• Ask Kiro to add a lightweight near-duplicate detector without external services.
• Normalize Tagalog text and compute token overlap.
• Flag examples with high similarity even when they are not exact duplicates.
• Export near-duplicate groups for review instead of deleting them automatically.

Kiro prompt sample

Create a local near-duplicate detector for Tagalog extra examples.
Normalize punctuation and case, compute Jaccard similarity over token sets, and flag pairs above 0.82.
Do not delete examples automatically.
Write duplicate candidates with example IDs, score, and reviewerDecision.

System design decision

• Exact duplicate checks are not enough: Examples can be nearly identical while still passing exact text comparison.
• Local scoring keeps the workshop deterministic: Token overlap is explainable and reproducible without external APIs.
• Reviewer decision remains human-owned: The detector flags candidates; reviewers decide whether to keep, rewrite, or block.

Code sample — near_duplicates.py

import re
from itertools import combinations


def tokens(text: str) -> set[str]:
    normalized = re.sub(r"[^\w\sñÑ]", " ", text.lower())
    return {part for part in normalized.split() if part}


def jaccard(left: str, right: str) -> float:
    a = tokens(left)
    b = tokens(right)
    if not a and not b:
        return 1.0
    return len(a & b) / len(a | b)


def near_duplicate_pairs(examples: list[dict], threshold: float = 0.82) -> list[dict]:
    findings = []
    for left, right in combinations(examples, 2):
        score = jaccard(left["tagalog"], right["tagalog"])
        if score >= threshold:
            findings.append({
                "leftExampleId": left["exampleId"],
                "rightExampleId": right["exampleId"],
                "score": round(score, 3),
                "reviewerDecision": ""
            })
    return findings

Code explanation

• Business logic: The detector finds examples that may feel repetitive to learners.
• Code logic: It normalizes text, computes Jaccard similarity, and returns candidate pairs above a threshold.
• Expected result: Reviewers get a near-duplicate report without losing any examples automatically.

Hands-on Lab C — Create a template diversity budget

Developer action

• Ask Kiro to define allowed template families for examples.
• Count how often each family appears per article and per category.
• Fail validation if one template family dominates a page.
• Add a report that recommends which template family to use next.

Kiro prompt sample

Create a template diversity budget for extra examples.
Template families include repeat, apply, ask, explain, and write-down.
No single family should exceed 45 percent of examples in an article.
Return article-level counts, failures, and suggested next family.

System design decision

• Uniqueness includes instructional variety: Three examples can be textually unique but pedagogically repetitive.
• Budgets prevent template overuse: A maximum share per family keeps generated examples varied.
• Recommendations help rewrite loops: The validator should say which template family would improve balance.

Code sample — template_budget.py

from collections import Counter, defaultdict

MAX_SHARE = 0.45
FAMILIES = ["repeat", "apply", "ask", "explain", "write-down"]


def article_template_report(examples: list[dict]) -> dict:
    grouped = defaultdict(list)
    for example in examples:
        grouped[example["articleNumber"]].append(example)

    reports = {}
    for article, rows in grouped.items():
        counts = Counter(row["templateFamily"] for row in rows)
        total = sum(counts.values()) or 1
        failures = [
            {"templateFamily": family, "share": count / total}
            for family, count in counts.items()
            if count / total > MAX_SHARE
        ]
        suggested = min(FAMILIES, key=lambda family: counts.get(family, 0))
        reports[article] = {"total": total, "counts": dict(counts), "failures": failures, "suggestedNextFamily": suggested}
    return reports

Code explanation

• Business logic: The report keeps extra examples varied across practice styles.
• Code logic: It groups examples by article, counts template families, flags dominant families, and recommends an underused family.
• Expected result: Developers can rewrite repetitive batches using concrete diversity feedback.

Hands-on Lab D — Build a rewrite queue for duplicate or weak examples

Developer action

• Ask Kiro to create a queue of examples that need rewriting.
• Add reasons such as exact-duplicate, near-duplicate, template-overused, and missing-politeness.
• Produce rewrite prompts that preserve the source sentence and traceability.
• Keep rewritten examples in draft status until reviewed.

Kiro prompt sample

Create a rewrite queue for weak extra examples.
Inputs are duplicate findings, near-duplicate findings, template budget failures, and validation failures.
For each queued item, produce exampleId, reason, sourceNaturalTagalog, currentTagalog, rewriteInstruction, and reviewStatus draft.
Do not overwrite the original example automatically.

System design decision

• Rewrite should be deliberate: Weak examples should enter a queue instead of being silently replaced.
• Reasons make review efficient: A reviewer can see why an example was flagged before approving a rewrite.
• Traceability remains intact: The rewrite keeps the original example ID and source sentence for comparison.

Code sample — rewrite_queue.py

from collections import defaultdict


def build_rewrite_queue(examples_by_id: dict[str, dict], findings: list[dict]) -> list[dict]:
    grouped_reasons = defaultdict(list)
    for finding in findings:
        grouped_reasons[finding["exampleId"]].append(finding["reason"])

    queue = []
    for example_id, reasons in grouped_reasons.items():
        example = examples_by_id[example_id]
        queue.append({
            "exampleId": example_id,
            "reason": sorted(set(reasons)),
            "sourceNaturalTagalog": example["sourceNaturalTagalog"],
            "currentTagalog": example["tagalog"],
            "rewriteInstruction": "Create a distinct beginner-friendly example that keeps the same source sentence context.",
            "reviewStatus": "draft",
            "reviewerDecision": ""
        })
    return queue

Code explanation

• Business logic: The queue turns QA findings into controlled rewrite work.
• Code logic: Findings are grouped by example ID, deduplicated by reason, and converted into reviewer-ready tasks.
• Expected result: Developers can rewrite flagged examples without losing original context.

Hands-on Lab E — Import reviewer decisions and apply safe updates

Developer action

• Ask Kiro to design a reviewer decision import format.
• Support decisions: approve, rewrite, block, and needs-discussion.
• Apply approved metadata updates to the example report.
• Refuse to publish blocked examples in learner-facing output.

Kiro prompt sample

Create a reviewer decision importer for extra examples.
Read reviewer-decisions.csv with exampleId, decision, reviewerNotes, revisedTagalog, revisedEnglish, and reviewedBy.
Apply approved rewrites only when revised text is non-empty.
Mark blocked examples as blocked and exclude them from learner-facing export.

System design decision

• Reviewer feedback must round-trip: CSV export is only useful if decisions can be imported safely.
• Safe updates avoid accidental blanks: Rewrites should not apply unless revised fields contain text.
• Blocked content should fail closed: Learner-facing exports should exclude blocked examples by default.

Code sample — import_reviewer_decisions.py

import csv

ALLOWED_DECISIONS = {"approve", "rewrite", "block", "needs-discussion"}


def apply_decisions(examples_by_id: dict[str, dict], csv_path: str) -> dict[str, dict]:
    with open(csv_path, newline="", encoding="utf-8") as file:
        for row in csv.DictReader(file):
            example_id = row["exampleId"]
            decision = row["decision"]
            if decision not in ALLOWED_DECISIONS or example_id not in examples_by_id:
                continue
            example = examples_by_id[example_id]
            example["reviewerDecision"] = decision
            example["reviewNotes"] = row.get("reviewerNotes", "")
            example["reviewedBy"] = row.get("reviewedBy", "")
            if decision == "block":
                example["reviewStatus"] = "blocked"
            if decision == "approve":
                example["reviewStatus"] = "native-reviewed"
            if decision == "rewrite" and row.get("revisedTagalog") and row.get("revisedEnglish"):
                example["tagalog"] = row["revisedTagalog"]
                example["english"] = row["revisedEnglish"]
                example["reviewStatus"] = "draft"
    return examples_by_id


def learner_examples(examples: list[dict]) -> list[dict]:
    return [example for example in examples if example.get("reviewStatus") != "blocked"]

Code explanation

• Business logic: Reviewer decisions become part of the content QA lifecycle.
• Code logic: The importer updates status, notes, reviewer identity, and safe rewrites while filtering blocked output.
• Expected result: Review feedback can be applied without manually editing large JSON files.

Hands-on Lab F — Generate a batch quality scorecard

Developer action

• Ask Kiro to create a scorecard for each example batch.
• Include exact duplicate count, near-duplicate count, missing review metadata, template dominance, blocked count, and approved count.
• Produce a pass/fail release recommendation.
• Save the scorecard as JSON and Markdown for handoff.

Kiro prompt sample

Create a batch quality scorecard for extra examples.
Inputs are examples, exact duplicate findings, near duplicate findings, template budget reports, and reviewer decisions.
Return metrics, pass/fail status, releaseRecommendation, and nextActions.
Write example-quality-scorecard.json and example-quality-scorecard.md.

System design decision

• Quality needs a release view: Individual validators are useful, but maintainers need one final summary.
• Scorecards make progress visible: Teams can track whether duplicate counts are decreasing and approved examples are increasing.
• Markdown supports human handoff: A readable report helps reviewers and workshop participants understand what remains.

Code sample — scorecard.py

import json
from pathlib import Path


def quality_scorecard(examples: list[dict], exact_duplicates: list[dict], near_duplicates: list[dict], template_failures: list[dict]) -> dict:
    blocked = sum(1 for example in examples if example.get("reviewStatus") == "blocked")
    approved = sum(1 for example in examples if example.get("reviewStatus") == "native-reviewed")
    missing_review = sum(1 for example in examples if not example.get("reviewStatus"))
    passed = not exact_duplicates and len(near_duplicates) <= 5 and not template_failures and missing_review == 0
    return {
        "totalExamples": len(examples),
        "approvedExamples": approved,
        "blockedExamples": blocked,
        "exactDuplicateCount": len(exact_duplicates),
        "nearDuplicateCount": len(near_duplicates),
        "templateFailureCount": len(template_failures),
        "missingReviewMetadata": missing_review,
        "status": "passed" if passed else "needs-work",
        "releaseRecommendation": "Ready for learner-facing export." if passed else "Resolve QA findings before release."
    }


def write_scorecard(scorecard: dict, json_path="example-quality-scorecard.json", md_path="example-quality-scorecard.md") -> None:
    Path(json_path).write_text(json.dumps(scorecard, indent=2), encoding="utf-8")
    lines = ["# Example Quality Scorecard", ""]
    for key, value in scorecard.items():
        lines.append(f"- **{key}:** {value}")
    Path(md_path).write_text("\n".join(lines) + "\n", encoding="utf-8")

Code explanation

• Business logic: The scorecard gives maintainers a release-readiness summary for extra examples.
• Code logic: Metrics are derived from examples and validator findings, then written as JSON and Markdown.
• Expected result: The batch has a clear pass/fail recommendation and actionable quality metrics.

Reference architecture notes

• Kiro capabilities emphasized in this workshop: example QA steering, stable identity design, near-duplicate analysis, template-diversity validation, rewrite queue generation, reviewer decision import, and release scorecard documentation.
• Product scope: extra examples for Tagalog learning cards. Generated examples remain draft until reviewed by native Tagalog speakers.
• Runtime scope: local Python QA pipeline first. Optional automation can later run the same checks in CI before exporting learner-facing examples.