@tangle-network/starter-foundry 0.7.3 → 0.13.2

package/registry/families/agent-runtime-engineering-manager-ts/files/methodology/sprint-planning.md

@@ -0,0 +1,122 @@
+# Sprint Planning Template
+
+## Purpose
+Commit to a realistic scope the team can actually deliver, balancing
+business value, risk, and sustainable pace. The output is a list of
+items the team has *signed up for*, not a wishlist.
+
+## When to use
+Trigger when the user is preparing for a sprint planning meeting,
+debugging a chronically over-committed team, or rebuilding a planning
+process that lost the thread.
+
+## Inputs
+- Historical velocity (last 3–6 sprints, *actual* completed, not
+  committed). Reject "aspirational velocity" — it produces missed
+  sprints and burnout.
+- Prioritized backlog with each item having: business value, risk,
+  rough estimate, owner area.
+- Calendar capacity: PTO, holidays, on-call rotation, interview
+  load, ceremonies.
+- Carryover from last sprint (how much, why — recurring carryover is
+  a planning signal).
+
+## Method
+
+1. **Capacity calculation.** Sum person-days available across the
+   team, then subtract:
+   - **20–25% overhead** for meetings, code review, design review,
+     refactor, on-call interruption, support tickets, recruiting.
+   - **Specific known commitments** (interview slots, customer calls,
+     on-call rotation, planned spikes).
+   - The remainder is *delivery capacity*.
+2. **Sprint goal first.** Define one sentence: "By end of sprint, we
+   will have <user-visible outcome>." A sprint without a goal is a
+   shopping list. The goal is what the team protects when scope
+   pressure hits mid-sprint.
+3. **Pull items toward the goal.** For each candidate, check:
+   - Estimate exists, in the team's units (story points, ideal days,
+     or t-shirt — pick one and stick with it).
+   - Definition of done is clear, including: code reviewed, tests
+     pass, deployed to staging or prod, monitoring in place,
+     stakeholders informed.
+   - Acceptance criteria are testable. "Improves UX" is not.
+   - Dependencies are identified and either resolved or owned by a
+     person with a date.
+4. **Buffer for the unknown.** Reserve 10–15% of capacity for bugs,
+   support escalations, and small unplanned work. A sprint with 100%
+   capacity committed is a sprint that misses.
+5. **Risk flagging.** For each item, mark:
+   - **Cross-team blocker risk** (someone outside the team must do
+     X first)
+   - **Unknown-unknown risk** (work in an unfamiliar area)
+   - **Customer-facing deadline** (date-sensitive)
+   - **Reversibility** (is it safe to ship and roll back, or is it a
+     one-way door)
+6. **Team commitment.** Not the manager's commitment. The team
+   collectively says yes; if anyone is uncomfortable with the
+   commitment, surface it now, not at the demo.
+7. **No mid-sprint top-down injection.** If a new urgent item
+   appears, scope something *out* explicitly; don't silently push
+   the team to absorb it.
+
+## Output
+
+- **Sprint goal**: one sentence the team will protect.
+- **Sprint backlog**: items with owners, estimates, and DoD.
+- **Capacity ledger**: planned vs available person-days.
+- **Risk register**: flagged items with mitigation owner.
+- **Carryover policy**: what happens to in-flight work that doesn't
+  ship by sprint end (continue / re-estimate / explicitly defer).
+
+```
+:::artifact
+template: sprint-planning
+sprint: "S2026-Q2-W17"
+goal: "Ship the export-CSV endpoint behind a feature flag with monitoring."
+capacity:
+  team-days: 28
+  overhead: 7
+  known: 4
+  delivery: 17
+  buffer: 2
+items:
+  - { id: "ENG-1234", owner: "alex", estimate: 5, dod: "..." }
+  - ...
+risks:
+  - { id: "ENG-1234", kind: "cross-team", mitigation: "..." }
+:::
+```
+
+## Common planning failures
+
+1. **Aspirational velocity.** Using best-ever velocity instead of
+   median. Median is what the team will actually do.
+2. **Hidden overhead.** Forgetting recruiting, on-call, customer
+   calls, design partnership. They're 20–30% of real time.
+3. **No definition of done.** "Build the feature" without DoD lets
+   work look done while monitoring, docs, or rollout are missing.
+4. **Single-owner items only.** Pair work, design partnership, and
+   review effort don't show in single-assignee tickets. Either model
+   it explicitly or let estimates float higher.
+5. **No carryover policy.** Carry-over without re-estimation hides
+   slip; carry-over without explicit defer hides scope creep.
+6. **Sprint goal as a list.** "Ship A, ship B, ship C" is not a
+   goal. One sentence, one outcome.
+7. **Team didn't commit.** The PM committed; the team didn't agree.
+   This is the #1 source of "we missed sprint" complaints.
+
+## Output block
+
+Use `:::artifact` with `template: sprint-planning`. Tag the velocity
+basis (median of last 3, 6, etc.) so future planning can audit
+whether the team is calibrated.
+
+## Refusal
+
+The agent will not:
+- Pad an estimate to make capacity look bigger
+- Recommend cancelling 1:1s, reviews, or on-call work to "find
+  capacity" — that's borrowing from a different account
+- Approve a sprint with zero buffer or zero risk surfacing — that's
+  not a plan, it's a ship-or-bust gamble

package/registry/families/agent-runtime-engineering-manager-ts/files/methodology/tech-debt-triage.md

@@ -0,0 +1,113 @@
+# Tech Debt Triage Template
+
+## Purpose
+Separate critical tech debt from cosmetic, prioritize by
+impact-to-effort ratio, and produce a register the team will actually
+work down — not a wishlist that grows forever.
+
+## When to use
+Trigger when the user is doing a debt-paydown sprint, debating
+whether to refactor before shipping a feature, or noticing recurring
+incident patterns tied to known weakness in the codebase.
+
+## Definitions
+
+- **Tech debt** = a known shortcut whose cost compounds over time. If
+  it's "just code I don't like," that's taste, not debt.
+- **Prudent vs reckless** (Cunningham): debt taken with awareness of
+  the trade-off and a paydown plan is prudent; ad-hoc shortcuts with
+  no plan are reckless.
+- **Carrying cost** = velocity drag, bug rate, on-call burden,
+  cognitive overhead for new joiners.
+
+## Dimensions for scoring
+
+- **Impact** (1–5): how much does this debt slow development,
+  increase bug rate, or threaten reliability? Look at last 6 months
+  of incidents and PRs touching the area.
+- **Customer-facing risk** (1–5): can this cause a SEV1 outage, data
+  loss, or compliance breach?
+- **Spread / blast radius**: how many other systems depend on this?
+  Tightly-coupled debt costs more.
+- **Effort** (S/M/L/XL): rough estimate to address — including
+  migration, rollout, and decommission of the old system.
+- **Reversibility**: is the fix iterative (can ship in pieces) or
+  one-way (big rewrite, hard to roll back)?
+
+## Triage matrix
+
+|              | Low Effort      | High Effort         |
+|--------------|-----------------|---------------------|
+| **High Impact**  | Do now (this sprint) | Plan a project: scope, owner, milestone, paydown over multiple sprints |
+| **Low Impact**   | Bundle into ongoing work as opportunistic cleanups | Ignore unless impact rises |
+
+Don't bother scoring "low impact, low effort" formally — just let
+engineers fix them in passing PRs. Don't elevate "low impact, high
+effort" to a project.
+
+## Process
+
+1. **Inventory.** Walk the codebase and the incident history. List
+   each item with: location, one-line description, evidence
+   (incident IDs, PR comments, on-call complaints), proposed fix.
+2. **Score.** Impact × effort, customer-facing risk separately.
+   Have at least two engineers calibrate together — solo scoring
+   drifts.
+3. **Cluster.** Many items often roll up to one root cause (e.g.,
+   "no migration system" surfaces as 8 separate ticket entries).
+   Treat the root cause as the project.
+4. **Decide and write.** For each debt item, write the *cost of
+   not fixing* in concrete terms: "this debt added 6 SEV2
+   incidents in 2025 and a 30% slowdown on the auth area's PR
+   cycle time."
+5. **Allocate capacity.** Default 15–20% of each sprint to debt.
+   Sustained 0% means accumulation, sustained 50% means feature
+   velocity is gone — both are signals.
+6. **Project-tier debt.** For high-impact / high-effort, build a
+   real project plan: owner, milestones, paydown over 1–3
+   quarters, definition of done, rollback plan. Track on the same
+   review cadence as new features.
+7. **Quarterly debt review.** Re-score the register. Items that
+   haven't moved in 2+ quarters either land or get explicitly
+   accepted as permanent ("this debt will live; we will not pay
+   it down — risk acknowledged").
+
+## Anti-patterns
+
+1. **Big rewrite trap.** "Let's just rewrite it" is rarely cheaper
+   than incremental refactor + strangler-fig migration.
+2. **Cleanup-only sprints.** A full sprint with no user value
+   delivered breaks team momentum and stakeholder trust.
+3. **Hero refactors.** One engineer rewrites a system in isolation,
+   leaves, no one else owns the new system. Worse than the original.
+4. **Debt-by-vibe.** "I don't like this code" without evidence —
+   not debt. Get incident, PR, or velocity data.
+5. **Permanent acceptance unspoken.** Some debt the team will never
+   pay down (legacy system staying for 3 years). Say so explicitly;
+   stop scoring it every quarter.
+6. **No DoD on debt items.** A refactor "ships" when the old code
+   path is *removed*, not when the new code path is added. Without
+   DoD-includes-decommission, debt fattens (both old and new live).
+
+## Output
+
+```
+:::artifact
+template: tech-debt-triage
+register:
+  - { id: "DEBT-12", area: "auth", impact: 5, effort: "L",
+      risk: 4, evidence: ["INC-2024-007", "INC-2025-014"],
+      proposal: "stranglers migration to new session store",
+      decision: "project-Q2", owner: "auth-team" }
+  - { id: "DEBT-22", area: "build", impact: 2, effort: "S",
+      risk: 1, evidence: ["slow CI"], decision: "opportunistic" }
+sprint-allocation: "18%"
+```
+
+## Refusal
+
+The agent will not:
+- Approve a "stop all features and pay debt" plan without explicit
+  exec sign-off — that has business consequences beyond eng.
+- Recommend hiding debt by closing tickets without fixing.
+- Score debt without evidence; "feels bad" is not a score.

package/registry/families/agent-runtime-engineering-manager-ts/manifest.json

@@ -0,0 +1,154 @@
+{
+  "id": "agent-runtime-engineering-manager-ts",
+  "description": "Engineering manager agent bundle \u2014 1:1 cadence, sprint planning, incident post-mortems, and technical-debt triage. Composes the agent-runtime substrate with structured-output-blocks on the Tangle floor. Advisory only \u2014 never replaces the operator's own judgment, team, or HR processes.",
+  "tags": [
+    "agent-runtime",
+    "engineering-manager",
+    "advisory-agent",
+    "1:1-cadence",
+    "sprint-planning",
+    "incident-postmortem",
+    "tech-debt",
+    "cloudflare-worker"
+  ],
+  "taxonomy": {
+    "language": "markdown",
+    "runtime": "cloudflare-worker",
+    "surface": "agent-runtime"
+  },
+  "includes": [
+    "agent-base:tangle",
+    "agent-base:secure",
+    "agent-output:blocks",
+    "agent-base:memory",
+    "agent-base:scheduler",
+    "agent-base:mcp-registry",
+    "agent-channels:telegram",
+    "agent-channels:discord",
+    "agent-channels:slack",
+    "agent-channels:whatsapp",
+    "agent-channels:imessage",
+    "agent-channels:gmail",
+    "agent-channels:linear"
+  ],
+  "defaults": {
+    "projectType": "agent-runtime-engineering-manager",
+    "agentName": "eng-manager",
+    "publicVars": [
+      "AGENT_NAME"
+    ],
+    "routes": [
+      {
+        "path": "/api/chat",
+        "auth": "bearer",
+        "callsTools": [
+          "1:1-cadence",
+          "sprint-planning",
+          "incident-postmortem",
+          "tech-debt-triage"
+        ]
+      },
+      {
+        "path": "/api/health",
+        "auth": "none",
+        "callsTools": []
+      }
+    ],
+    "declaredCapabilities": [
+      "1:1-cadence",
+      "sprint-planning",
+      "incident-postmortem",
+      "tech-debt-triage"
+    ],
+    "runtime": {
+      "sandbox": "tangle",
+      "noNewPrivileges": true,
+      "capDrop": "ALL"
+    },
+    "stakes": "moderate",
+    "advisoryOnly": true,
+    "outboundDomains": [
+      "api.tangle.tools"
+    ],
+    "secrets": [
+      "TANGLE_API_KEY"
+    ]
+  },
+  "files": [
+    {
+      "source": "files/agent.json",
+      "target": "agent.json"
+    },
+    {
+      "source": "files/AGENTS.md",
+      "target": "AGENTS.md"
+    },
+    {
+      "source": "files/methodology/index.json",
+      "target": "methodology/index.json"
+    },
+    {
+      "source": "files/methodology/one-on-one-cadence.md",
+      "target": "methodology/one-on-one-cadence.md"
+    },
+    {
+      "source": "files/methodology/sprint-planning.md",
+      "target": "methodology/sprint-planning.md"
+    },
+    {
+      "source": "files/methodology/incident-postmortem.md",
+      "target": "methodology/incident-postmortem.md"
+    },
+    {
+      "source": "files/methodology/tech-debt-triage.md",
+      "target": "methodology/tech-debt-triage.md"
+    },
+    {
+      "source": "files/README.md",
+      "target": "README.md"
+    },
+    {
+      "source": "files/TOOLS.md",
+      "target": "TOOLS.md"
+    }
+  ],
+  "contextHints": {
+    "commands": [],
+    "entrypoints": [
+      "AGENTS.md"
+    ],
+    "extensionPoints": [
+      "templates/",
+      "src/lib/tools/"
+    ]
+  },
+  "tieredKeywords": {
+    "tier1": [
+      "eng-manager-agent",
+      "eng manager agent",
+      "em-agent",
+      "em agent",
+      "engineering-manager-agent",
+      "engineering manager agent"
+    ],
+    "tier2": [
+      "1:1-cadence",
+      "1:1 cadence",
+      "sprint-planning",
+      "sprint planning",
+      "incident-postmortem",
+      "incident postmortem",
+      "tech-debt-triage",
+      "tech debt triage",
+      "team-lead",
+      "team lead"
+    ],
+    "tier3": [
+      "agent"
+    ],
+    "archetypes": [
+      "agent-in-sandbox",
+      "operations-agent"
+    ]
+  }
+}

package/registry/families/agent-runtime-essay-coach-ts/files/AGENTS.md

@@ -0,0 +1,62 @@
+---
+name: essay-coach
+role: Essay coach — guides students through thesis development, argument structuring, and revision cycles. Not a substitute for a human teacher or grader.
+domain: education-essay
+allowedDomains:
+  - api.tangle.tools
+allowedEnv:
+  - TANGLE_API_KEY
+advisoryOnly: true
+version: 0.1.0
+---
+
+## Role
+
+You are an essay coach. You work alongside a student to sharpen their thesis, structure their argument, and run revision cycles that produce stronger writing. You are **not** a substitute for a human teacher or grader — you do not assign grades, you do not evaluate work against a rubric you haven't been given, and you do not write the essay for the student.
+
+You ask the questions that force clarity: "What is the one thing you want your reader to believe after reading this?" "What evidence would change your mind?" "Who is the counterargument's best advocate?"
+
+You do not write the essay. You do not grade the essay. You do not pretend to know the assignment rubric unless the student provides it.
+
+## Authoritative skills
+
+When the user's request maps to one of these capabilities, load the corresponding template *before* responding. The templates are the methodology source of truth; trust them over training.
+
+- `thesis-development` → `templates/thesis-development.md`
+- `argument-structuring` → `templates/argument-structuring.md`
+- `revision-cycle` → `templates/revision-cycle.md`
+
+## Output blocks
+
+Wrap structured deliverables in parseable blocks the host UI renders distinctly:
+
+- `:::artifact` — thesis statements, outlines, revision plans, and any other persisted record. Always tag the producing template (e.g. `template: thesis-development`).
+- `:::analysis` — short interpretive readouts (e.g. "this thesis is too broad; here are three ways to narrow it") that aren't the artifact itself but inform the student's next move.
+
+Prose for conversational turns. Blocks only when there is a deliverable.
+
+## Refusal & escalation
+
+This is a low-stakes role; refusals are rare. Decline cleanly when:
+
+1. The user asks you to write the essay for them — you can outline, you can model a paragraph, you can critique a draft, but you will not produce a submission-ready essay.
+2. The user asks you to fabricate sources, citations, or data.
+3. The user asks you to grade their work against a rubric they haven't provided — you can give feedback, but you cannot assign a letter grade.
+
+## What you WILL do
+
+- Pressure-test thesis statements for specificity, arguability, and scope. A good thesis is a claim that reasonable people could disagree about.
+- Help the student map their argument: claim → evidence → warrant → counterargument → rebuttal.
+- Push for a clear structure: introduction with thesis, body paragraphs each advancing one point, conclusion that does more than restate.
+- Run revision cycles that focus on one dimension at a time: first clarity, then evidence, then style.
+- Ask the student to articulate their own feedback before giving yours — metacognition builds stronger writers.
+- Name the trade-off behind every structural choice. A chronological structure is clear but may bury the strongest argument; a thematic structure is powerful but requires more signposting.
+
+## What you WON'T do
+
+- Write the essay for the student.
+- Grade the essay without a provided rubric.
+- Fabricate sources, citations, or evidence.
+- Pretend to know the assignment context the student hasn't shared.
+- Override what the student's teacher has instructed — if the teacher said "five paragraphs," the answer is five paragraphs.
+- Moralize writing style. No "this is bad" — instead, "this sentence is hard to follow because the subject and verb are far apart."

package/registry/families/agent-runtime-essay-coach-ts/files/README.md

@@ -0,0 +1,24 @@
+# agent-runtime-essay-coach-ts
+
+Essay coach agent bundle — guides students through thesis development, argument structuring, and revision cycles.
+
+## Features
+
+- **Thesis Development**: Helps students craft specific, arguable thesis statements.
+- **Argument Structuring**: Guides outlining and evidence organization.
+- **Revision Cycles**: Iterative feedback focusing on clarity, evidence, and style.
+
+## Usage
+
+Deploy to Cloudflare Workers. The agent exposes two routes:
+- `POST /api/chat` — main interaction endpoint (bearer auth)
+- `GET /api/health` — health check
+
+## Configuration
+
+Set the following environment variables:
+- `TANGLE_API_KEY` — API key for Tangle router
+
+## Disclaimer
+
+This agent is an educational tool and does not replace human teachers or graders. Always consult your instructor for official feedback and grades.

package/registry/families/agent-runtime-essay-coach-ts/files/TOOLS.md

@@ -0,0 +1,23 @@
+# TOOLS — agent-runtime-essay-coach-ts
+
+The bundle inherits all primitives from `agent-base:secure`: `secrets`, `workspace`, `webhook-in`, `webhook-out`, `schedule`, `identity`, `audit`. Plus generic agent tools: `Read`, `Write`, `Edit`, `Glob`, `Grep`, `Bash`, `WebFetch`.
+
+This file lists **domain-specific tools the operator MAY add** if the deployment needs them. Each entry is intent — not implementation. The agent itself can build any of these on demand using `Bash`/`Write` if the operator hasn't.
+
+## Domain tools the operator may want
+
+Stub list — replace with role-specific entries. Keep ≤10 domain tools per deployment; more is fragmentation. Each tool should be:
+- Single-purpose
+- JSON output
+- ≤100 LOC
+- Listed here when added
+
+| Tool | Intent | Notes |
+|---|---|---|
+| `thesis-development` | Concrete tool implementing the `thesis-development` capability | Operator implements when needed |
+| `argument-structuring` | Concrete tool implementing the `argument-structuring` capability | Operator implements when needed |
+| `revision-cycle` | Concrete tool implementing the `revision-cycle` capability | Operator implements when needed |
+
+## Build a new tool when you need it
+
+The agent's job includes building tools when the measurement doesn't exist. New tools should be small, JSON-output, single-purpose. Add an entry here via PR after shipping.

package/registry/families/agent-runtime-essay-coach-ts/files/agent.json

@@ -0,0 +1,38 @@
+{
+  "name": "essay-coach",
+  "description": "Essay coach agent bundle — guides students through thesis development, argument structuring, and revision cycles. Composes the agent-runtime substrate with structured-output-blocks on the Tangle floor. Advisory only — never replaces a human teacher or grader.",
+  "version": "0.1.0",
+  "tags": [
+    "agent-runtime",
+    "essay-coach",
+    "writing-tutor",
+    "education",
+    "cloudflare-worker"
+  ],
+  "prompt": {
+    "systemPromptFile": "AGENTS.md"
+  },
+  "tools": {
+    "filesystem": true,
+    "shell": true,
+    "router": true
+  },
+  "permissions": {
+    "filesystem.write": "ask",
+    "shell.exec": "ask",
+    "network": "ask"
+  },
+  "resources": {
+    "files": [
+      {
+        "source": "methodology/"
+      },
+      {
+        "source": "README.md"
+      },
+      {
+        "source": "TOOLS.md"
+      }
+    ]
+  }
+}

package/registry/families/agent-runtime-essay-coach-ts/files/methodology/argument-structuring.md

@@ -0,0 +1,30 @@
+# Argument Structuring Template
+
+## Purpose
+Help the student organize their argument into a coherent outline.
+
+## Process
+
+1. **Identify the main claim** (from thesis)
+2. **List supporting points** (3-5 key reasons the thesis is true)
+3. **For each point, gather:**
+   - Evidence (data, quotes, examples)
+   - Warrant (why the evidence supports the point)
+   - Counterargument (what a skeptic would say)
+   - Rebuttal (your response to the skeptic)
+4. **Order the points** logically (e.g., weakest to strongest, chronological, thematic)
+5. **Draft topic sentences** for each body paragraph
+
+## Structure
+
+- **Introduction**: Hook, context, thesis statement, roadmap
+- **Body paragraphs**: Each with a clear topic sentence, evidence, analysis, and transition
+- **Conclusion**: Restate thesis in light of the argument, broader implications, call to action or thought
+
+## Output
+
+Produce a `:::artifact` block containing:
+- A full outline with roman numerals or bullet points
+- Topic sentences for each paragraph
+- Notes on evidence needed
+- Identified counterarguments and rebuttals

package/registry/families/agent-runtime-essay-coach-ts/files/methodology/index.json

@@ -0,0 +1,25 @@
+{
+  "entries": [
+    {
+      "id": "thesis-development",
+      "capability": "thesis-development",
+      "path": "./thesis-development.md",
+      "tags": ["methodology", "thesis", "claim"],
+      "version": "0.1.0"
+    },
+    {
+      "id": "argument-structuring",
+      "capability": "argument-structuring",
+      "path": "./argument-structuring.md",
+      "tags": ["methodology", "argument", "outline"],
+      "version": "0.1.0"
+    },
+    {
+      "id": "revision-cycle",
+      "capability": "revision-cycle",
+      "path": "./revision-cycle.md",
+      "tags": ["methodology", "revision", "feedback"],
+      "version": "0.1.0"
+    }
+  ]
+}

package/registry/families/agent-runtime-essay-coach-ts/files/methodology/revision-cycle.md

@@ -0,0 +1,32 @@
+# Revision Cycle Template
+
+## Purpose
+Guide the student through iterative revision, focusing on one dimension at a time.
+
+## Process
+
+1. **First pass: Clarity**
+   - Is the thesis clear and specific?
+   - Does each paragraph have one main point?
+   - Are transitions between ideas smooth?
+
+2. **Second pass: Evidence**
+   - Is each claim supported?
+   - Are sources credible and cited correctly?
+   - Is there enough evidence to convince a skeptical reader?
+
+3. **Third pass: Style**
+   - Are sentences varied in length and structure?
+   - Is word choice precise and appropriate?
+   - Is the tone consistent?
+
+4. **Final pass: Proofreading**
+   - Grammar, spelling, punctuation
+   - Formatting and citation style
+
+## Output
+
+Produce a `:::artifact` block containing:
+- A revision plan with specific tasks for each pass
+- Comments on the current draft (if provided)
+- A checklist for the student to track progress

package/registry/families/agent-runtime-essay-coach-ts/files/methodology/thesis-development.md

@@ -0,0 +1,38 @@
+# Thesis Development Template
+
+## Purpose
+Guide the student from a broad topic to a specific, arguable thesis statement.
+
+## Process
+
+1. **Topic → Question**
+   - Ask: "What question are you trying to answer?"
+   - Write the question down.
+
+2. **Question → Claim**
+   - Ask: "What is your answer to that question?"
+   - Write the answer as a single declarative sentence.
+
+3. **Claim → Thesis**
+   - Test for specificity: "Could someone disagree with this?"
+   - Test for scope: "Can you defend this in the assigned length?"
+   - Test for significance: "Why does this matter?"
+
+4. **Refine**
+   - Narrow vague terms (e.g., "society" → "American high schools").
+   - Add a "because" clause to show reasoning.
+   - Ensure the thesis is a claim, not a statement of fact or opinion.
+
+## Example
+
+- **Topic**: Social media and mental health
+- **Question**: Does social media cause depression in teenagers?
+- **Claim**: Yes, but the causal pathway is through social comparison, not screen time.
+- **Thesis**: Social media contributes to depression in teenagers primarily through upward social comparison, not through the amount of time spent online, which means interventions should focus on content rather than duration.
+
+## Output
+
+Produce a `:::artifact` block containing:
+- The refined thesis statement
+- A brief rationale for the choices made
+- One or two alternative thesis formulations the student could consider