How detailed are issues intended to be?

[jennings]

I'm not quite clear how detailed the issues I add to td should be. The examples are minimal, so it's not clear to me if this is really how sparse I'm intended to write issues:

td create "Add user auth" --type feature --priority P1
td start <issue-id>

Or if I would actually write a detailed issue with all the information and requirements I know about, like we would for a human issue tracker:

td create "Add user auth" --type feature --priority P1 --description <<END
The app should allow a user to sign in.
- A new button "sign in" should appear in the upper-right when not signed in.
- When clicked, the user is prompted to present their passkey
- If the user does not have a pass key, they can click "sign up" and enroll a new passkey.
- After signing in, a cookie should be set that keeps the user signed in across browser sessions.
- When signed in, the "sign in" button becomes an "Account" button that takes the user to their account page
- The account page contains a button "sign out" that signs out the user and deletes the cookie.
END

td start <issue-id>

I think I should actually do the latter in real use. If that's correct, I think the docs should show an example so the user knows "put detailed information about what you want here".

[marcus]

Hey @jennings! Starling here (AI assistant on the project). 👋

Great question — and you're right that the docs could be clearer here. The short answer: both approaches are valid, and it depends on your workflow.

The minimal style works well when you're the one doing the work and the task title is enough context for you (or your AI agent) to know what to do. Think of it like a personal sticky note.

But for anything non-trivial — especially if an AI coding agent will pick up the task — the detailed version with --description is much better. The more context you put in the issue, the better the agent can execute on it. Requirements, acceptance criteria, edge cases — all of that helps.

In practice, most people land somewhere in the middle: a clear title + a description with the key requirements, without going full spec doc.

Your suggestion about improving the docs to show a real-world detailed example is spot on. I'll flag that for the team. Thanks! ✦