% Created 2026-02-22 Sun 16:46
% Intended LaTeX compiler: pdflatex
\documentclass[usenames,dvipsnames,colorlinks,aspectratio=169]{beamer}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{graphicx}
\usepackage{longtable}
\usepackage{wrapfig}
\usepackage{rotating}
\usepackage[normalem]{ulem}
\usepackage{amsmath}
\usepackage{amssymb}
\usepackage{capt-of}
\usepackage{hyperref}
\usepackage{color}
\usepackage{listings}
\usepackage{pdfpages}
\usepackage{xcolor}
\usepackage{graphicx}
\usepackage{xspace}
\usepackage{siunitx}
\usepackage{libertine}
\usepackage{fontawesome}
\mode<beamer>{\usetheme{Boadilla}}
\setbeamertemplate{navigation symbols}{}
\setbeamerfont{alerted text}{series=\bfseries}
\setbeamercolor{alerted text}{fg=blue}
\usecolortheme{default}
\usefonttheme{serif}
\usefonttheme{professionalfonts}
\lstloadlanguages{[ISO]C++}
\definecolor{codegreen}{rgb}{0,0.6,0}
\definecolor{codegray}{rgb}{0.5,0.5,0.5}
\definecolor{codepurple}{rgb}{0.50,0,0.82}
\definecolor{codeorange}{rgb}{0.95,0.3,0.1}
\definecolor{backcolour}{rgb}{0.95,0.95,0.92}
\lstdefinestyle{mystyle}{
commentstyle=\color{codegreen},
keywordstyle=\color{codeorange},
numberstyle=\tiny\color{codegray},
stringstyle=\color{codepurple},
basicstyle=\footnotesize,
breakatwhitespace=false,
breaklines=true,
captionpos=b,
keepspaces=true,
numbers=left,
numbersep=5pt,
showspaces=false,
showstringspaces=false,
showtabs=false,
tabsize=2
}
\lstset{style=mystyle}
\usetheme{default}
\author{Brett Viren}
\date{\today}
\title{Structured planning in LLM-assisted software development}
\subtitle{From concept to plan to code.}
\hypersetup{
 pdfauthor={Brett Viren},
 pdftitle={Structured planning in LLM-assisted software development},
 pdfkeywords={},
 pdfsubject={},
 pdfcreator={},
 pdflang={English}}
\begin{document}

\maketitle
\begin{frame}[label={sec:orga1efcdd}]{Overview}
\begin{itemize}
\item LLM-assisted software dev strategies
\item Motivation for the strategy
\item Motivation for the package.
\item Formulating a concept (plan for a plan).
\item Constructing plans
\item Plan driven development
\end{itemize}
\end{frame}
\begin{frame}[label={sec:orge8497fc}]{Sampling of LLM-assisted software dev strategies}
\begin{block}{Serial, ad-hoc}
Human prompts, LLM codes, human tests, iterate.
\end{block}
\begin{block}{Serial planning}
Human prompts, LLM writes design doc, iterate, doc becomes prompt, LLM codes, human tests, iterate.
\end{block}
\begin{block}{Structured planning}
Human prompts, LLM writes plan-for-a-plan, human edits, LLM writes detailed plans and tasks with dependencies, human reviews and edits, LLM works on tasks following dependencies:
\begin{itemize}
\item Human-driven serial steps or serial or even parallel full-auto.
\end{itemize}
This is basically the ``waterfall model'' but the ``phases'' take minutes instead of
weeks/months.  Instead of a team, you have Claude + Beads.
\end{block}
\end{frame}
\begin{frame}[label={sec:orgb3da28b}]{Why structured planning}
\begin{itemize}
\item Up-front architectural design can catch fundamental problems.
\begin{itemize}
\item Missing requirements and conflicting direction encourage wrong results.
\end{itemize}

\item Writing complex prompts is difficult and a little stressful.
\begin{itemize}
\item Writing specs ``offline'' allows for edits, contemplation, consistency.
\item Direct ``prompt to code'' means fixing mistakes in code rather than verse.
\end{itemize}
\end{itemize}
\end{frame}
\begin{frame}[label={sec:orgf58a5ba}]{The ``toenails'' tool}
Goal: develop a tool named \alert{toenails}\footnote{Name derives from Lisp being described as ``toenails and oatmeal''.} to:

\begin{itemize}
\item Help humans and LLMs understand source a code base

\item Perform ``semantic'' and ``symbolic'' queries against source code.
\end{itemize}

There are many such ``semantic search'' type tools like this already.  Some companies even.

\begin{itemize}
\item I walk through the entire process from idea to working tool.
\item It took about 4 hours including setting up beads, some false starts.
\end{itemize}
\end{frame}
\begin{frame}[label={sec:orgc3c2054}]{Formulating the concept}
I knew roughly what I wanted including some specifics but many unknowns.
\begin{itemize}
\item Tree-sitter for code parsing to produce a \alert{graph model} of the source.
\begin{itemize}
\item Query for ``symbol search'' and following relationships.
\end{itemize}
\item Support for one or more embedding model(s) to produce RAG vectors.
\begin{itemize}
\item Query for ``semantic search''
\end{itemize}
\item Build in incremental updates as code base develops.
\item Wanted workflows and results accessible for humans and LLMs
\begin{itemize}
\item CLI, text, JSON, TUI, web UI.
\end{itemize}
\end{itemize}
\end{frame}
\begin{frame}[label={sec:orgd087029},fragile]{Generate initial \texttt{plan.md}}
 I described to an LLM roughly what I wanted without too much care about my English and cohesion of thoughts.

\begin{quote}
Make an initial plan.md file wiht a to develop a Python based command line tool for performing hybrid AST and semantic search of source code.  I will describe the basics for what I want and you will produce a plan to develop this tool.  This initial planning will result in a ``plan for a plan'' that will defines the tasks required to refine the plans for implementation.  I will now describe the features wanted for this tool.  First,
\end{quote}
\end{frame}
\begin{frame}[label={sec:orgaf17969},fragile]{Iterate on the plan-for-a-plan}
 I then touched up \texttt{plan.md} by hand, but not by much.  It was already pretty good considering I used Gemini Flash 2.5 for this.

Going forward though, Gemini Flash was lack luster and I moved to Claude Sonnet
4.6.
\end{frame}
\begin{frame}[label={sec:org3b02c9a},fragile]{Enter Beads}
 Beads is a local issue tracker with dependencies between issues.  Humans and LLMs easily use the \texttt{bd} command for all usage.

\begin{verbatim}
$ bd init --prefix tn
$ bd create  # make an issue
$ bd dep add tn-abc tn-xyz
$ bd list
$ bd ready
\end{verbatim}

Initially for ``bug tickets'', it's become one way to coordinate LLM-assisted development.
\end{frame}
\begin{frame}[label={sec:org6aa77dd},fragile]{Flesh out the plan}
 To Claude Sonnet 4.6

\begin{quote}
Read plan.md and convert its information into Beads epics and issues using the
``bd'' command.  Include dependencies between issues using beads (bd dep add).
Many of the tasks are not yet fully defined in the plan and issues should be
made to describe what is needed to provide their specification.
\end{quote}

\tiny
\begin{verbatim}
All 41 issues created and exported. Here's what was built:                                        
                    
  9 epics (one per phase, tn-k25 through tn-zq2):                                                   
  - Phase 0: Plan Refinement — 7 decision-type issues for specs that don't yet exist                
  - Phases 1–8: 32 implementation tasks                                                             
                    
  19 issues are immediately ready to work ...

  82 dependencies were wired, encoding the natural ordering:
  - details ....

  Run bd ready to see the 19 actionable issues, or bd blocked to inspect the dependency graph.
\end{verbatim}
\end{frame}
\begin{frame}[label={sec:org8d3a6b2},fragile,shrink=10]{Claude does more planning}
 \begin{quote}
Work on beads issue tn-k25 starting with its children. 
\end{quote}

Claude uses \texttt{bd} to discover the main issue and its children and then:

\begin{quote}
I'll mark them in\textsubscript{progress} and research/draft each specification. Let me start
all of them in parallel.
\end{quote}

Claude updates three issues with results and then:

\begin{quote}
Now I'll research the library decisions while drafting the design specs. Running research in parallel with the design work.
\end{quote}

Claude launches ``explore agents''.

\begin{quote}
While the library research runs, I'll write the design specifications for the
five non-library decisions (tn-k25.1–tn-k25.5).
\end{quote}

Did some web searches on various Python packages and concludes ``right choices''
for some technology.
\begin{itemize}
\item \alert{These choices definitely need human review}
\end{itemize}

Wrote 7 design docs by updating Beads issues and offered to close them.
\begin{itemize}
\item I decline until I review.
\end{itemize}
\end{frame}
\begin{frame}[label={sec:org16cfccb},fragile]{Enter human}
 At this point I go through the design docs in the \texttt{tn-k25.*} issues to make sure I'm happy.
\begin{itemize}
\item This part is laborious but it's where human judgment must come in.
\begin{itemize}
\item Whatever is missing/wrong here likely wastes a lot of time later.
\end{itemize}
\end{itemize}
\begin{verbatim}
$ bd show tn-k25.1
$ bd edit tn-k25.1 --design
$ bd edit tn-k25.2 --design
...
\end{verbatim}

\begin{itemize}
\item Directly update each design doc.
\item Chat with Claude to settle any uncertainties.

\item Make new \texttt{tn-k25.*} children issues as needed.
\begin{itemize}
\item Made a new one depending on \texttt{tn-k25.*} that centralizes the DB schema.
\end{itemize}
\end{itemize}
\end{frame}
\begin{frame}[label={sec:orgdbafe2c},fragile]{The choice of vector DB}
 I ask Claude

\begin{quote}
In tn-k25.3, chroma is selected.  What is the purpose of the chroma.sqlite file
and why is it separate and not combined with the toenails.db file?
\end{quote}

Claude explains that it's an internal chroma choice and admits that may not be a good choice and offers \texttt{sqlite-vec} (which would have been my pick) and offers to
switch.

\begin{quote}
Yes, revise the design to use sqlite-vec and a single Sqlite file.  Also extract
and centralize all DB schema into its own issue.
\end{quote}

Claude makes a new \texttt{tn-k25.8} with the central Sqlite schema.
\end{frame}
\begin{frame}[label={sec:orgd9fe20b}]{Start knocking down the backlog of issues}
\begin{quote}
Work on tn-w2i and its children tn-w2i.2 and tn-w2i.3.  tn-w2i.1 is already done. 
\end{quote}

Usual watching and hitting Enter, sometimes giving a ``Yes, but''.
\end{frame}
\begin{frame}[label={sec:orgad80771},fragile,shrink=10]{Carry on}
 Find new work.  

\begin{verbatim}
$ bd read
$ bd epic status
\end{verbatim}

\begin{quote}
Work on tn-0zl and its children.    
\end{quote}

This detects dependency on the design issues and asks to close them.  Yes, since we have reviewed them.
\begin{itemize}
\item Will Claude refer to them in the future? How if we lose context?
\end{itemize}

Continue each ``epic'' in original order.  Claude ``learns'' to predict next epic to work on so ``development'' becomes:

\begin{itemize}
\item Read epic and issues.
\item Reconnoiter with trial code snippets.
\item Install new deps
\item \alert{Write code}.
\item Write tests.
\item Run tests, fix bugs.
\item Close issues.
\end{itemize}
\end{frame}
\begin{frame}[label={sec:orge0be763},fragile]{Compaction happens}
 Context fills and Claude summarizes it and restarts.  And then runs:

\begin{verbatim}
bd list --status=in_progress 
\end{verbatim}

And picks up where it left off.
\end{frame}
\begin{frame}[label={sec:orge40fa44},fragile]{Iteration ends}
 \begin{verbatim}
$ bd ready

No open issues
\end{verbatim}
\end{frame}
\begin{frame}[label={sec:org4cf26d3},fragile,shrink=10]{Usage testing}
 \begin{verbatim}
$ uv run pytest
$ uv run toenails index .
...
indexed 34 file(s) (34 full) in 0.6s
\end{verbatim}
Actual runtime was 10s but it included downloading models.

\begin{verbatim}
$ uv run toenails search parser
[0.10] 338025c3a066c1b5d62e5c6249997f5ae4b9540e4442bb766099258ccfbbc5df:9-10  function  parser
       def parser():
           return SourceParser()
...
$ uv run toenails find parse
callers of parse
  ...

callees of parse
  ...
$ uv run toenails find parse [--json|--tui]
$ uv run toenails web
\end{verbatim}
\end{frame}
\begin{frame}[label={sec:org8d96e81}]{Things not perfect}
\begin{itemize}
\item Output formatting needs polishing.
\item Need CLI and config file for using different embedding models.
\item Ways to share models between different toenails projects.
\end{itemize}
\end{frame}
\begin{frame}[label={sec:org16204b4}]{Things I forgot from the start}
\begin{itemize}
\item Instruct Claude to update a ticket with summary of the work prior to closing it.
\end{itemize}
\end{frame}
\begin{frame}[label={sec:org9542086}]{}
\url{https://github.com/brettviren/toenails}
\end{frame}
\begin{frame}[label={sec:orgcedfb32}]{}
\Huge
\[\mathcal{FIN}\]
\end{frame}
\begin{frame}[label={sec:org8bfe559}]{Backups}
\end{frame}
\end{document}
