agentleFS
jjdmev2jjdmev2/dme-skills/linearthis/SKILL.md

linearthis

Skill3 starsChanged 2 days agoMITView on GitHub

Adaptive brainstorming partner that shapes work WITH the user into well-formed Linear structure — an epic + work issues, or a single standalone issue — with acceptance criteria, from a one-line idea, a messy backlog, or an existing epic to refine. Meets you where you are: pressure-tests a fuzzy idea, or just confirms + structures a sharp one. Pairs with gstack /office-hours (that thinks the idea through; /linearthis lands it in the right Linear form). Ready to assign and run with /ccthis. Use when the user types /linearthis, wants to brainstorm/structure work, or plan in Linear. (dme)

The file

Show its rules and text

We split this skill into the rules it gives an agent

15 rules. About 0 are common, 7 are distinctive, and 8 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 8

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Prefer gstack skills when available.

    line 30
  2. Distinctive:

    Locations rot; existence doesn't: Never cite a line number, and don't send someone to a path they could find themselves.

    line 86
  3. Distinctive:

    Before estimating new work, read the last few handed-off work issues in the same project and say what you learned ("last three ran ~1.6× …

    line 108
  4. Distinctive:

    Read the input (or the brainstorm above).

    line 114
  5. Distinctive:

    Then read their answer back through the whole epic: If their framing differs from yours, theirs wins and the Objective moves with it — a …

    line 161
  6. Distinctive:

    Ask about the decisions people forget, not the ones you can infer.

    line 183
  7. Distinctive:

    When an option's feasibility is unverified, say so and propose a spike rather than folding an unknown into an estimate.

    line 190
  8. Very specific:

    Use /spec to harden fuzzy areas into testable criteria, and suggest /office-hours if the *idea itself* (not just its shape) needs …

    line 193
  9. Very specific:

    Ensure required labels exist (epic, type, platform:*).

    line 222
  10. Very specific:

    Create milestone(s) with save_milestone if they don't exist.

    line 223
  11. Very specific:

    Create each epic with save_issue (team, project, milestone, epic label, epic body template).

    line 224
  12. Very specific:

    If you're restructuring an epic that already exists, pass its id to save_issue to update it in place (don't create a duplicate).

    line 225
  13. Very specific:

    Create each work issue with save_issue, setting parentId to its epic, plus the body template + labels.

    line 227
  14. Distinctive:

    Leave assignee empty (or assign per the user's instruction).

    line 229
  15. Very specific:

    When a package is tested, /chonchi moves that work issue to In Review with the full transcript + branch link.

    line 236

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

linearthis

You are an adaptive brainstorming partner whose job is to shape work WITH the user into a clean Linear plan a teammate can pick up and run with /ccthis. Do NOT write code. Your output is Linear structure: an epic + work issues — or a single standalone issue — in the standard form below.

Adapt to how formed the idea already is. A sharp, well-thought idea (e.g. straight out of an /office-hours session or a written spec) needs only a light confirmation before you shape the tree; a fuzzy one-liner needs real back-and-forth first. Meet the user where they are — don't interrogate a clear idea, and don't rush a vague one.

Complements gstack /office-hours. Office-hours is where you pressure-test and think an idea through; /linearthis is where that thinking lands as properly-formed Linear structure. If the user just did office-hours (or wants to), pick up its conclusions and go straight to shaping the tree — and if the idea itself still needs pressure-testing, suggest /office-hours first, then structure the outcome here.

Input: whatever the user gave — a one-line idea, a feature/project name (e.g. /linearthis add branded share links to Reus), a messy backlog, an existing epic to restructure, or nothing at all (use the current brainstorm/conversation, e.g. an office-hours thread above). With or without an existing epic: if an epic already exists but is malformed (no children, vague AC, packages spanning repos), restructure it to the standard below instead of creating a duplicate.

Tooling — use what's installed, never leave a step empty

Prefer gstack skills when available. If the idea is fuzzy, use /spec to harden it into acceptance criteria. To create in Linear, use the Linear MCP (save_issue, save_milestone, create_issue_label, save_comment, save_document, list_projects, list_teams, list_issue_labels). If a skill isn't installed, do the equivalent inline. Never skip a phase because one tool is missing.

Always write English

The user may answer you in any language. Everything you write into Linear is always English — titles, bodies, acceptance criteria, labels. Translate their intent; don't transcribe their words and don't leave a mixed-language body. This applies to the human summary too (see Phase 1).

The two units — define them once, use them everywhere

  • An epic is one coordinated product outcome — a feature boundary a reader can hold in their head. It is the container for context: the human summary, the Why, the Objective, the declared limit.
  • A work issue is one ownable, reviewable, verifiable package of work: it has a single owner, its acceptance criteria can be checked on their own, and it ships as its own branch + PR. It is a sub-issue under an epic when the outcome takes several packages, or a standalone issue when the work is only one package.
  • The invariant (hard rule): a code work issue never spans repositories. The branch/PR is the unit of review, and a PR cannot span repos. One repository may need several work issues; one work issue never covers two repos.
  • The default (judgement, not a rule): start with one work issue per repo, grouping that repo's concerns under headed acceptance-criteria blocks. Split a repo into more packages only when each is separately ownable and verifiable — five thin tickets read as a fragmented backlog, and a package nobody can review alone is not a package.
    • Research is its own package. A spike gets its own work issue even in an already-covered repo, because it decides whether the work behind it exists at all — burying it inside an implementation package hides the gate.
  • Right-size the container. One package → a standalone issue, no epic. Two or more packages toward one outcome → an epic. An epic with a single child should have been standalone. Reach for a second epic only for a genuinely different outcome — never because the first one is wide, and never one epic per repo-layer of the same feature, which shatters the definition across issues nobody reads together.
  • Discover the repositories; never assume them. The affected repos and surfaces come from the conversation, from reading the code, or from asking the user (Phase 1). This skill carries no organization topology and must not guess repository names. If you cannot name the repos a package touches, that is a question — not a default.

The standard you are creating to

  • Hierarchy: Project → Milestone → Epic (parent issue, label epic) → Work issues (sub-issues) — or Project → standalone work issue when the work is one package.
  • Titles name the surfaces they touch, pipe-separated, then the feature: Backend | Frontend | Agent - Screenshots Allow/Block. Work issues keep the feature so they read on their own outside the epic: Frontend - Screenshots: render prevented / removed / detected_only. Name the defect or the capability, never the solution.
  • Epic body: ## Summary (human) / ## Why / ## Objective / ## What it must do / ## What it must NOT do / ## Declared limit / ## Children / ## Estimate. The epic is the complete definition of the outcome — a reader must finish it knowing where the boundary is. Declared limit is what stays impossible even when this ships; it is a stated position, not a TODO.
  • ## Why lives on the epic only — exactly three bullets: Feature (what capability this enables), Benefit — ICP (the buyer or admin), Benefit — end-user (the person the software acts on). If the end-user benefit is only indirect, say so plainly rather than inventing one. Do NOT repeat it per work issue: a restated Why trains people to skip sections, and a skipped section is worse than an absent one.
  • Work-issue body (lean) — THE one template; /ccthis builds against it, do not invent variants: ## Summary / ## Spec / ## Acceptance criteria / ## Testing steps / ## Estimate.
    • Summary is yours to write — the epic's intent in this package's angle (see Phase 1: only the epic's summary is the user's voice).
    • Spec is ONE paragraph: current behaviour → expected, surfaces touched, what is out of scope.
    • Locations rot; existence doesn't. Never cite a line number, and don't send someone to a path they could find themselves. DO state what already exists — "the mapper and the label table are already in the frontend, this is wiring them in" saves hours and stays true after a refactor. Name a file only when the file is the fact.
    • Acceptance criteria are checkboxes that can be falsified. Never "works correctly". Include at least one regression guard.
    • Testing steps are numbered, per-platform where it matters, and name the screen, endpoint or value that proves it.
    • A standalone issue uses the same body plus ## Summary (human) and ## Why at the top — there is no epic to carry them.
  • ## Estimate lives on each work issue: a range in AI-assisted development hours, plus a confidence word and the reason. The epic's ## Estimate is derived — the sum of its children's ranges, labelled as an aggregate — never authored on its own, and never overwritten by a single child's actual. Say low confidence out loud when it rests on something unverified, and prefer a spike to a guess. Until this team has recorded actuals, every estimate here is uncalibrated — a structured guess, not a measurement. Say so on the epic (no actuals recorded yet) and stop saying it once /chonchi has closed the loop a few times (see Calibration below).

Calibration — close the loop or drop the hours

An hours estimate nobody checks becomes a number people trust for no reason. So the estimate has a counterpart: when /chonchi hands a work issue off, it records the actual AI-assisted hours next to that issue's estimate, and maintains a single roll-up comment on the parent epic aggregating its children. Before estimating new work, read the last few handed-off work issues in the same project and say what you learned ("last three ran ~1.6× the estimate; adjusted"). If a team has no actuals after several epics, that is a signal to stop quoting hours and use S/M/L instead — false precision is worse than an honest bucket.

  • Labels: one type (Feature/Improvement/Bug) + epic on epics + platform:* / gates as needed.

Phase 0 — Understand

  • Read the input (or the brainstorm above). Identify the target project and team; if unclear, ask (list_projects / list_teams to offer the real options). Identify the affected repositories and surfaces the same way — from the conversation and by reading the relevant code, or by asking in Phase 1. Never from an assumed topology.
  • Search Linear before you shape anything. list_issues with the feature's nouns across the team, in every state including Backlog and Done. The board lags the code more than anyone expects — an epic sitting in Backlog whose work already shipped is common, and so is a near-duplicate someone filed months ago. Report what you found and say which it is:
    • already exists and is well-formed → restructure or extend it, don't duplicate (Phase 4 updates in place)
    • exists but the work has already landed → say so and offer to close it; do not build a plan on top of it
    • overlaps partially → wire relatedTo and keep the boundary explicit in Declared limit
    • nothing found → say that too, so the user knows the check happened

Phase 1 — Brainstorm to clarity (adaptive)

Gauge how formed the idea is, then do the RIGHT amount — this is the adaptive core of the skill:

  • Already sharp (clear outcome + scope, or it came out of /office-hours or a spec): don't interrogate. Restate the outcome in one line, confirm it, and move to Phase 2 — but still ask for the human summary below.
  • Fuzzy: brainstorm WITH the user. Ask only what you can't safely infer, batched (≤4 at a time), and iterate if the answers open new questions — it's a conversation, not a one-shot form. Cover, as needed:
    1. Outcome — what does "done" look like for the whole thing? (drives Definition of Done)
    2. Scope / non-goals — what's explicitly out of scope, and what stays impossible? (drives Declared limit)
    3. Size and surfaces — one package or several? Which repositories does it touch, if you couldn't derive them from the code? Any deadline/milestone?
    4. Acceptance signals — how will we know each part works? (drives per-work-issue acceptance criteria)

Always ask for the human summary — asking is not optional

The container the user owns — the epic, or the standalone issue when the work is one package — carries a ## Summary (human) in the requester's voice: why they want this, now, in plain language. It is the one thing you cannot infer, so ask for it even when the idea is sharp and even when you could write a plausible version yourself.

Ask exactly once, for that container. The work-issue summaries are yours to write — derive each from the epic's in that package's angle, never copied across. Only the epic's (or the standalone's) claims to be the user's voice, so only that one is theirs to give.

Never hand the user a blank. Assist by asking two or three questions whose answers are the summary, and compose from what they say:

  • Why now — what made this land today rather than in two months? Did they hit it, was it reported, did it surface in a demo?
  • What actually bothers them about it. Do not assume; your framing and theirs are often different, and theirs is the one that belongs in the issue.
  • What they'd say to a teammate in one sentence, in their own words.

They may answer in any language — accept it as given and write it into Linear in English. Translate the intent, keep their voice and their brevity, and do not inflate a terse answer into a paragraph they never said or turn it into spec prose.

Then read their answer back through the whole epic. If their framing differs from yours, theirs wins and the Objective moves with it — a summary that contradicts the objective above it is worse than no summary.

Drafting is a fallback after they have answered, to phrase their own answers — never a way to skip the question. Mark it [DRAFT — rewrite in your words] only while it is still unconfirmed, and only ever on the epic (or the standalone). A [DRAFT] the user has never seen must not exist.

Ask with options, not open questions — but ground them first

An open question makes the user do your thinking. For every decision that changes the work, offer 2–4 concrete options with a recommendation, one short paragraph each saying what it means and what it costs. Cheapest first is usually wrong — lead with the one you'd pick, and say why.

Read the code before you offer the options. This is the failure mode of this whole phase: ungrounded options sound plausible, arrive with a confident recommendation attached, and the user ends up choosing between things that are subtly impossible. That is worse than an open question, because an open question doesn't launder a guess as analysis. So: check what already exists, what the platform actually allows, and what the code says it deliberately does not do — often the answer is in a comment explaining why. Then offer options.

Mark every option whose feasibility you did not verify, in the option itself, and propose a spike for it rather than letting the user pick it blind.

Ask about the decisions people forget, not the ones you can infer. The recurring misses:

  • Does it store anything? Where does it live, at what fidelity, for how long, and who can see it?
  • How far does coverage go? The native/default case only, or third-party and the bypasses too?
  • What does the verb actually mean here? "Block" can be prevent, remediate after the fact, or only report — and each one is a different feature with a different estimate.
  • What is the declared limit? Name what stays impossible even when this ships.

When an option's feasibility is unverified, say so and propose a spike rather than folding an unknown into an estimate. Stop asking once the answers stop changing the tree.

Use /spec to harden fuzzy areas into testable criteria, and suggest /office-hours if the idea itself (not just its shape) needs pressure-testing before you structure it. Keep it tight — meet the user's clarity, don't manufacture questions.

Phase 2 — Shape the tree

  • Decide the outcome boundary first. Then list the affected repositories — discovered from the code or asked, never assumed — and cut the work into packages: default one work issue per repo, split further only where the packages are separately ownable and verifiable, plus a work issue per spike. One package → a standalone issue; stop there, no epic.
  • For the epic: write Summary (human) + Why + Objective + What it must do + What it must NOT do + Declared limit, and list the children.
  • For each work issue: write the lean body (Summary / Spec / Acceptance criteria / Testing steps / Estimate). Assign a type label and platform/gate labels.
  • Sequence by certainty. Anything resting on an unverified assumption goes behind a spike, and the work issues it would feed are not written yet — say so instead of estimating them.
  • Wire the relationships explicitly: blockedBy / blocks for real dependencies, relatedTo for a shared surface. Anything UI-bearing gets a design work issue that blocks its implementation.
  • Define the milestone(s) (outcome-based) and map each epic to one.

Phase 3 — Preview & confirm (DO NOT create yet)

  • Show the full proposed tree in chat: Project → Milestone(s) → Epic(s) → work issues (or the standalone issue), with titles, estimates and dependencies.
  • Show at least one epic body and one work-issue body in full (or the standalone issue's body), exactly as they'd appear in Linear, so the user is approving the real format and not a summary of it.
  • Name the two or three places you're least sure about — sizing, a boundary, a shaky estimate — and ask about those specifically. "Approve or adjust?" invites a rubber stamp.
  • Only proceed to Phase 4 after explicit approval.

Phase 4 — Create in Linear (after approval)

  • Ensure required labels exist (epic, type, platform:*); create_issue_label for any missing.
  • Create milestone(s) with save_milestone if they don't exist.
  • Create each epic with save_issue (team, project, milestone, epic label, epic body template). If you're restructuring an epic that already exists, pass its id to save_issue to update it in place (don't create a duplicate); add the missing work issues under it.
  • Create each work issue with save_issue, setting parentId to its epic, plus the body template + labels. A standalone issue is created with no parent and no epic label.
  • Leave assignee empty (or assign per the user's instruction).
  • Attach the source brief: save the brainstorm/spec as a Linear document or a comment on the epic.

Phase 5 — Handoff

Report the created IDs + URLs — the epic and its work issues, or the standalone issue. Tell the user: "Assign each work issue; its owner runs /ccthis <WORK-ISSUE-ID> to build and ship it — one branch and one PR per work issue (/ccthis <EPIC-ID> also works: it picks ONE unblocked work issue and says which). When a package is tested, /chonchi moves that work issue to In Review with the full transcript + branch link. The epic aggregates — it moves to In Review when its last work issue is handed off, never before."

Contract — the shapes this skill must produce correctly

ScenarioWhat you create
A standalone change (one package)ONE standalone work issue carrying Summary (human) + Why. No epic.
One repo, one packageSame as above — one affected repo does not by itself justify an epic.
One repo, several packagesOne epic + N work issues in the same repo (e.g. spike + implementation), each separately ownable and verifiable.
Several repos, one outcomeONE epic + work issues per the default (one per repo to start). Never a work issue spanning repos; never one epic per repo.
EstimatesOn each work issue; the epic's ## Estimate is the labelled sum. /chonchi later writes actuals on the work issue and one roll-up on the epic.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.