Skills documentation

Thread model

Use one thread for one line of work. Put the top-level goal and context in the thread title and body. Then use replies to branch the discussion without overwriting prior thinking.

• goal for the original objective or problem statement
• proposal for concrete approaches
• review and comment for critique and discussion
• decision for choosing a direction
• implementation for concrete work updates
• verification for validation and closeout
• question for clarifications, unknowns, and review follow-ups

Recommended operating loop

1. Create a thread with the goal, constraints, and current understanding.
2. Add one or more proposal replies instead of editing the thread body repeatedly.
3. Add review replies that challenge the proposal, point out risks, and refine the plan.
4. Add a decision reply when a direction is chosen.
5. Add implementation replies for concrete coding work, commit links, or PR links.
6. Add verification replies with test results, review outcomes, and any remaining follow-up.
7. Update the thread status when the work is decided, implemented, or closed.

Branching and iteration

Prefer adding new replies over rewriting old ones. This preserves the reasoning trail and makes it clear how one proposal was reviewed, revised, accepted, or superseded.

• Use sibling replies when exploring competing approaches.
• Use child replies when refining or reviewing a specific proposal.
• Use decision replies to mark one branch as the chosen path.
• Use update statuses to mark replies as accepted, rejected, superseded, or resolved.

Linking commits and pulls

Replies can carry structured links. In the CLI, repeat --link=kind:target to attach them.

ghit-cli update-reply teams/platform/website \
  42 \
  9c4f1464-f353-4f00-8aa9-169b4a91168d \
  --status=accepted \
  --link=commit:e9ce311 \
  --link=pull:17 \
  --link=path:src/web/repo.rs

Keep kind simple and colon-free. The CLI splits on the first :, so additional colons are fine inside the target value.

Example workflow

A concrete feature workflow with threads and replies might look like this:

ghit-cli create-thread teams/platform/website \
  --title="Add Git HTTP password auth" \
  --body="Goal: allow password auth for Git smart-HTTP without changing API auth."

ghit-cli create-reply teams/platform/website \
  42 \
  --kind=proposal \
  --title="Token-first Basic auth fallback" \
  --body="Check API token first, then username/email + password when username is non-empty."

ghit-cli create-reply teams/platform/website \
  42 \
  --kind=review \
  --body="Do not sniff token-looking values by length. Check the DB verbatim."

ghit-cli create-reply teams/platform/website \
  42 \
  --kind=decision \
  --body="Proceed with token-first lookup, no token sniffing, no fallback on inactive/expired token."

ghit-cli create-reply teams/platform/website \
  42 \
  --kind=implementation \
  --body=- \
  --link=commit:e9ce311

ghit-cli create-reply teams/platform/website \
  42 \
  --kind=verification \
  --body="foreman run -- just ready passed; Git auth regression tests added."

ghit-cli update-thread teams/platform/website \
  42 \
  --status=implemented