Earlier quoted context omitted.
Technology evolves and traditions change. What persists is the role, not the filename and its extension. Weddings are still weddings even after things went from painted portraits to film cameras to camcorders to smartphones to livestreams. Same with birthdays. Cards became phone calls, Facebook wall posts, group chats, shared albums, or generated videos (Sora, RIP). The tradition of having a deck of punch cards evolv…
> The important part is a human-auditable directive, not an opaque, generated artifact as the thing that matters. Your arguments create a false dichotomy. You look at it from consumer perspective, while coding and it's artifacts are usually done by suppliers. If you change camcorder to tv advertisement, the requirements shift. The human auditable directive and the outcome matter. Coca Cola probably has very high stan…
Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML
291–300 of 316 posts
Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML
#292Earlier quoted context omitted.
I don’t understand how that relates to AI psychosis?
I guess I misappropriated the term then, woops. AI OCD? AI obsession? Whatever you call the behavior that I saw myself and others falling in to. Getting obnoxiously fixated on the tooling and the models to a counterproductive degree.
Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML
#293Earlier quoted context omitted.
This is a particular artifact of the government system process. These are contracted pieces of work that Company A would deliver, Company B would administer, and Company C would be contracted out for additional work. Further, all specifications were created ahead of time because changes would cost extra. (Anyone who has done government contracting can talk to the shenanigans involved with it - I have not lived in thi…
> This is a particular artifact of the government system process. Yes, a government process meant to implement the waterfall approach. If you look at Dr. Royce's paper which originated the concept, he was very explicit that it required upwards of thousands of pages of documentation to be written up front, if you were doing it "right". By the time the required documentation had all been written, there should be essent…
(and my link to the Royce paper isn't working anymore - I need to fix that!) - I am planning on a followup that takes the last 3 years of change in mind.
Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML
#294Earlier quoted context omitted.
I've been attaching to my commit messages a Git Trailer [1] of the Session UUID from the Claude Code conversation that created that commit. It allows Claude to look back into the session where a change was made and see the decisions made, tradeoffs discussed and other history not captured by code, tests. [1] https://git-scm.com/docs/git-interpret-trailers
A few questions: - Does Claude leverage the trailers automatically, or is usage initiated by you? - How often are you using the trailer lookups? - Any idea how this relates to token usage? If you're frequently busting cache on old sessions, it might be cheaper to read a local doc.
Trailers hint is in my global CLAUDE.md so it knows: when debugging, saying something like "didn't we already discuss this in a previous session?" it will know what to look for.
I also have a manually invoked `/search-session-transcripts` that I can use to natural-language inspect previous session by day, project, session id etc. Claude often uses this skill to narrow down on parts of the conversation that are relevant to the current query.
> How often are you using the trailer lookups?
Mondays are usually the day I need to refer to previous sessions from the week before. Trailer lookups are also good for continuing buildout of adjacent features. They've also been excellent in incident post-mortems where the PR text and commit message aren't enough to gauge the "how" of decisions that led to issues.
> Any idea how this relates to token usage?
I tested this. Session-transcripts are append-only so `/clear` and `/compact` don't clear out old messages, they stay stable and accessible. I also don't clean out my `~/.claude/sessions` ever so there's a lot in there, but the info is valuable and cheap.
Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML
#295Anything [prefix]maxxing just sounds so bad. It just feels so Andrew Tate...
Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML
#296Earlier quoted context omitted.
> This is a particular artifact of the government system process. Yes, a government process meant to implement the waterfall approach. If you look at Dr. Royce's paper which originated the concept, he was very explicit that it required upwards of thousands of pages of documentation to be written up front, if you were doing it "right". By the time the required documentation had all been written, there should be essent…
I wrote about this - https://www.ebiester.com/agile/2023/04/22/what-agile-alterna... - Royce was describing what he saw as an anti-pattern that it was risky and invited failure without iterations. (and my link to the Royce paper isn't working anymore - I need to fix that!) - I am planning on a followup that takes the last 3 years of change in mind.
Yes, that's why his paper essentially said "you're going to have to build two." One to figure out the mistakes you can't predict ahead of time, and the second for the real deal. Do your best to get through the first one as fast as you can, but still deliberate enough that there won't be any bugs left behind for the second one.
But a third or subsequent iteration was definitely a failure in his mind, and even building two (or one-and-a-half, depending on your framing) was simply a concession to the reality that actual implementation would run into unpredictable issues, for much the same reason computer science had already learned the halting problem was undecidable.
I have a book with his paper and to the extent he speaks of iteration as desirable, it is only iteration between succeeding steps of the overall 'waterfall'. E.g. in an ideal world you iterate between system requirements and their decomposition into software requirements (updating the system reqs as necessary to ensure the software reqs you're writing are accounted for). Likewise for system requirements to software analysis, and so on.
As you point out, he mentions that this concept is “risky and invites failure”, and goes on to allow for re-refinement and re-implementation of the software requirements and program design phases based on experience from the testing phase. But he goes on to emphasize: “However, I believe the illustrated approach [waterfall with reimplementation post-test] to be fundamentally sound”.
The rest of his paper then goes into the detail of these phases, and he specifically notes early on that there is a natural question, of how much documentation is enough? And he gives a very clear answer: “My own view is ‘quite a lot’; certainly more than most programmers, analysts or program designers are willing to do if left to their own devices.”
It's not an accident that the DoD software acquisition requirements based on waterfall as mentioned by the other comments were so numerous or onerous. As Dr. Royce puts it:
- “The first rule of managing software development is ruthless enforcement of documentation requirements”
- When asked to review software projects the first thing he does is review the documentation. If the documentation is seriously lacking his recommendation is to replace the whole project management and shift 100% of work to fixing documentation.
- “Management of software is simply impossible without a very high degree of documentation”
- If procuring a $5M hardware device he'd expect a 30 page spec to suffice. If procuring a $5M software system, he'd “... estimate a 1,500 page specification is about right.”
I wasn't pulling "thousands of pages" from thin air. It's right in his paper and he's extremely clear about this. It's not an off-hand remark, he goes on to justify why he thinks that mass of documentation is required.
I want to emphasize that he's writing from the problems he was facing in his era. Computer systems necessarily were room-sized installations, interactive computer time was incredibly expensive, but paper was cheap. There was no Internet to speak of to share powerful and efficient open-source libraries. There was no "continuous deployment" or "continuous integration".
The system had to work well pretty quickly after the subsystems were built, installed, integrated and tested or this newfangled computer system that cost millions in 1960s dollars to run per month would be nothing more than a money sink while the nerds tried to troubleshoot.
Nowadays we don't develop under those kinds of strictures and we've put tremendous investments into allowing real useful systems to be developed using the simpler processes that even back then were much easier to develop around, when it could be used (Dr. Royce's paper even leads off by describing the 'nice' process as he explains why you can't use it as system size grows). The voluminous test documentation he's propose are things we pretty much do write today, but we call them test suites and we grow them along with the program, rather than write them all months before coding.
I think there's a lot to be said for what a modern-day waterfall process might look like with the technologies and iteration speeds available to us now, the only problem is that I think it will still resemble agile more than it would resemble the process Dr. Royce described.
Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML
#297Earlier quoted context omitted.
A few questions: - Does Claude leverage the trailers automatically, or is usage initiated by you? - How often are you using the trailer lookups? - Any idea how this relates to token usage? If you're frequently busting cache on old sessions, it might be cheaper to read a local doc.
> Does Claude leverage the trailers automatically, or is usage initiated by you? Trailers hint is in my global CLAUDE.md so it knows: when debugging, saying something like "didn't we already discuss this in a previous session?" it will know what to look for. I also have a manually invoked `/search-session-transcripts` that I can use to natural-language inspect previous session by day, project, session id etc. Claude…
Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML
#298Earlier quoted context omitted.
I guess I misappropriated the term then, woops. AI OCD? AI obsession? Whatever you call the behavior that I saw myself and others falling in to. Getting obnoxiously fixated on the tooling and the models to a counterproductive degree.
you did, it has nothing to do with psychosis. as someone who has experienced psychosis you really should be more respectful about using mental health terms you don’t und
Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML
#299The author is right but his message ain’t specsmaxing, because while somewhat understandable as a rationale what does it actually mean? In other words: specs can be as detailed as it gets, and this is why developers have a hard time when they face as a senior an NDAed regulated environment. It ain’t software craftsmanship but data flow, hardware components, compliance on the lowest level including supply chains often…
Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML
#300Earlier quoted context omitted.
Software engineering is different from other engineering disciplines in that the most explicit spec of the thing you’re building is the actual thing itself. When you want to build a bridge you finalize all the blueprints and then someone goes and actually pours concrete, in software the blueprint is the code, and the code is also the bridge. However there are different levels of abstraction for writing specs and code…
> When you want to build a bridge you finalize all the blueprints and then someone goes and actually pours concrete Construction has plans "as designed" and "as built".