Concrete guidance in New task>new instead of aphorisms; a test plan with every key

tui/newtask.go

@@ -224,19 +224,42 @@ func (m newTaskModel) previewLines(width int) []string {
 	return out
 }
 
+// guidanceLines answers the four questions the form asks, with examples rather
+// than metaphors. If a line here needs a second reading, it is the wrong line.
 func (m newTaskModel) guidanceLines(width int) []string {
-	out := []string{"", groupHeading("what a task needs", 4, width-2), ""}
-	add := func(k, v string) {
-		out = append(out, " "+lipgloss.NewStyle().Foreground(lipgloss.Color(active.Accent)).Render(k))
-		for _, ln := range wrap(v, max(8, width-4)) {
+	out := []string{"", groupHeading("the five fields", -1, width-2), ""}
+	add := func(field, what, example string) {
+		out = append(out, " "+lipgloss.NewStyle().Foreground(lipgloss.Color(active.Accent)).Bold(true).Render(field))
+		for _, ln := range wrap(what, max(8, width-4)) {
+			out = append(out, "   "+mutedStyle2().Render(ln))
+		}
+		out = append(out, "   "+dimStyle().Render("example: "+example))
+		out = append(out, "")
+	}
+	add("Title", "One sentence naming the change. It becomes the task title in Paperclip.",
+		"Add a CHANGELOG.md with an Unreleased section")
+	add("What it must do", "The files to create or change, by path, and the exact behaviour. Mention what must NOT be touched.",
+		"Create CHANGELOG.md at the repository root. One section titled Unreleased with three bullets. Change no other file. Commit it.")
+	add("Must finish first", "The identifier of another task, for example AUD-171. Paperclip then records a real blocker edge and will not let this task run before that one is done. Leave it empty when nothing must come first.",
+		"AUD-171")
+	add("Proves it is done", "A shell command that exits 0 only when the work is right. It runs in the task's own copy of the code. Leave it empty and the task will be accepted on the agent's word, which is a weaker test.",
+		"test -s CHANGELOG.md      or      make test")
+	add("Assign to", "yes, or empty. yes hands the task to the configured agent as soon as it is created; empty leaves it for a person to assign on the board.",
+		"yes")
+
+	out = append(out, groupHeading("what these words mean", -1, width-2), "")
+	for _, pair := range [][2]string{
+		{"blocker", "Another task that must reach done before this one may start. It is a link between two tasks in Paperclip, not a sentence."},
+		{"verify command", "The command that decides the task is finished. Run in the task's worktree; exit 0 means finished."},
+		{"assign", "Giving the task to one agent. That is what wakes the agent and makes it start work."},
+		{"worktree", "The task's own copy of the repository, made by Paperclip. Two tasks cannot overwrite each other because of it."},
+	} {
+		out = append(out, " "+lipgloss.NewStyle().Foreground(lipgloss.Color(active.Text)).Render(pair[0]))
+		for _, ln := range wrap(pair[1], max(8, width-4)) {
 			out = append(out, "   "+mutedStyle2().Render(ln))
 		}
 		out = append(out, "")
 	}
-	add("one thing", "A task that asks for two things cannot be judged, only argued about.")
-	add("a command", "The verify command decides when the work is finished. The agent does not.")
-	add("a boundary", "Say which files may change. An unbounded task is how a review becomes an autopsy.")
-	add("a blocker", "If it must wait, name the task it waits for. A sentence in the description is not a blocker.")
 	return out
 }