Triage new issues

An issue that says “checkout is slow” can’t be picked up by a person or an agent until someone asks what it means. Here you find those issues as they arrive, and label them.

You'll end with

.github/workflows/triage.yml in your repository. It labels each new issue not-ready when task-readiness finds it too vague or too large to start.

! ready no

You need

• decide, installed
• An API key: get one
• A GitHub repository where you can add a workflow

1. Get the demo

   decide’s repository has six sample issues, some clear and some vague:

   git clone --depth 1 https://github.com/deepnoodle-ai/decide
   cd decide/demo

   If you already cloned decide for another tutorial, skip the first line.

2. Judge the issues

   task-readiness asks two questions about each issue: is it ready to start, and how large is it? It flags an issue that is probably not ready, or probably too large for one pull request. Judge the issues, then read the three nearest their flags:

   ~/decide/demo

   decide run task-readiness issues.json > /dev/null
   decide runs view --top 3

   Output as text

   $ decide run task-readiness issues.json > /dev/null
   Running task-readiness on 6 records · typesafe jev-latest
   
   ✓ 6 answered  ! 3 flagged  800ms
   Flagged: issues.json[1], issues.json[3], issues.json[5]
   See these results again with: decide runs view 20261008-045537-0aa8
   $ decide runs view --top 3
   Run 20261008-045537-0aa8 · task-readiness on issues.json · 2 seconds ago
   
   issues.json[3]  {"number":104,"title":"Move to multi-currency billing","b…
   ! ready  no      95%
   ! size   large   100%
   
   issues.json[1]  {"number":102,"title":"Checkout is slow","body":"Customer…
   ! ready  no      98%
     size   large   51%
   
   issues.json[5]  {"number":106,"title":"Update the docs","body":"The docs …
   ! ready  no      97%
     size   medium  58%
   
   The 3 of 6 answered items nearest their flags, flagged ones first.
   ✓ 6 answered  ! 3 flagged
   Flagged: issues.json[1], issues.json[3], issues.json[5]

   Three of six issues are flagged as not ready: “Checkout is slow”, “Move to multi-currency billing” and “Update the docs”. Each says what is wrong but not what to change or how to tell when it’s done.

   A JSON array is read one record at a time, so each issue is one item. runs view reads the saved run, so it asks the model nothing.

3. Add the workflow

   Add your key as a repository secret named TYPESAFE_API_KEY, and create a not-ready label. Then save this as .github/workflows/triage.yml:

   .github/workflows/triage.yml

   name: triage
   
   on:
     issues:
       types: [opened]
   
   permissions:
     issues: write
   
   jobs:
     readiness:
       runs-on: ubuntu-latest
       steps:
         - name: Install decide
           run: |
             base=https://github.com/deepnoodle-ai/decide/releases/latest/download
             curl -fsSLO "$base/decide_linux_amd64.tar.gz"
             curl -fsSLO "$base/checksums.txt"
             sha256sum --check --ignore-missing checksums.txt
             tar -xzf decide_linux_amd64.tar.gz decide
             sudo mv decide /usr/local/bin/
   
         - name: Label the issue if it isn't ready
           env:
             TYPESAFE_API_KEY: ${{ secrets.TYPESAFE_API_KEY }}
             GH_TOKEN: ${{ github.token }}
             TITLE: ${{ github.event.issue.title }}
             BODY: ${{ github.event.issue.body }}
             NUMBER: ${{ github.event.issue.number }}
           run: |
             status=0
             printf '%s\n\n%s\n' "$TITLE" "$BODY" |
               decide run task-readiness --each file --fail-on flagged ||
               status=$?
             if [ "$status" -eq 2 ]; then
               gh issue edit "$NUMBER" --repo "$GITHUB_REPOSITORY" --add-label not-ready
             elif [ "$status" -ne 0 ]; then
               exit "$status"
             fi

   --each file makes the whole issue one item, since piped text is otherwise judged line by line. Pass the issue’s text through env, as above. Never write ${{ github.event.issue.body }} into the script, where an issue’s text could run commands.

   Each new issue is one request on your key, and on a public repository anyone can open one. On a busy repository, add a condition to the job, such as if: github.event.issue.author_association != 'NONE', to judge only issues from people who have contributed before.

4. Check that it works

   Run the workflow’s command on a vague issue, and print the exit code:

   ~/decide/demo

   TITLE='Checkout is slow'; BODY='Customers say checkout feels slow.'
   printf '%s\n\n%s\n' "$TITLE" "$BODY" |
     decide run task-readiness --each file --fail-on flagged
   echo $?

   Output as text

   $ TITLE='Checkout is slow'; BODY='Customers say checkout feels slow.'
   $ printf '%s\n\n%s\n' "$TITLE" "$BODY" |
   >   decide run task-readiness --each file --fail-on flagged
   Running task-readiness on 1 file · typesafe jev-latest
   
   stdin
   ! ready  no      98%
     size   small   57%
   
   ✓ 1 answered  ! 1 flagged  300ms
   See these results again with: decide runs view 20261008-045513-7218
   Exiting with code 2 because 1 item was flagged (--fail-on flagged)
   $ echo $?
   2

   The issue is flagged as not ready, and decide exits with code 2, so the workflow adds the label. Open an issue in your repository to see it run in GitHub.

What next

Review pull requestsJudge each changed function, then block a merge.

Built-in templatestask-readiness, triage, ticket-routing, and the rest.