Add problem doc for advanced linting guardrails#53
Conversation
Describes considerations for maintainable agentic code and limiting human cognitive debt. Signed-off-by: Ryan Cole <rcyoalne@gmail.com>
14rcole
force-pushed
the
problem-cognitive-debt.md
branch
from
44bc0f3 to
553a69c
Compare
|
|
||
| ## The Problem: Cognitive Debt | ||
|
|
||
| The problem documents that have been created in fullsend thus far repeatedly mention the value of implicit and institutional knowledge to engineers. Less focus has been given to the impacts of the loss of institutional knowledge as the percentage of code contributions made by AI agents increases. There is a wealth of anecdotes from companies that have adopted agentic workflows about the increase in cognitive debt caused by the loss of this knowledge. This makes it harder for humans to contribute or debug when a problem occurs. This is primarily a risk in the middle period of fully-agentic workfllow adoption: the period in which agents are contributing a lot of code but nowhere near all of it. Ensuring that agents contribute quality code can limit knowledge loss. Some of the guardrails described below can be implemented at review-time or implementation-time. By implementing solutions at review-time, we can also improve the quality of human contributions. These are problems that engineering teams have tried to solve since long before the availability of AI tools. While agents give us the ability to create or improve guardrails that we never could before, agentic code also increases the consequences of not having these guardrails. |
There was a problem hiding this comment.
Ah, check docs/problems/human-factors.md, #32, and experiments/003-agent-outage-fire-drill.md for some prior art. Can you ask claude to analyze those files and assess whether or not your contribution should be decomposed and added to those docs, or kept here as a standalone doc. Either way, we should cross link this doc with those and vice versa.
There was a problem hiding this comment.
Apologies for the delay, I had to prioritize some other work. Claude recommends rolling the doc into #32. Since that PR is still open, do you want me to work with Mike to pull it all into one PR or should I wait until his initial doc is merged before adding to it?
Full output:
Merge into cognitive-debt.md, with cross-references preserved.
Specifically:
Problem framing — The "Why it matters" argument in maintainable-code.md largely duplicates cognitive-debt.md. Drop it in the merge; it's already said.
Guardrails section — Add a new mitigation subsection to cognitive-debt.md covering the four code-level guardrails (naming, refactoring, comments, testing). This is the substantive, novel content worth preserving.
Pitfalls section — Fits naturally as a caveat beneath the new mitigation subsection, since it speaks to the difficulty of defining and enforcing these guardrails.
Open questions — Several of the open questions (particularly the third bullet about experiments) could fold into cognitive-debt.md's existing open questions section; others could stand alongside the new guardrails subsection.
Cross-references — cognitive-debt.md should gain a reference to human-factors.md noting the code-level guardrails as partial mitigations for expertise atrophy. experiments/003 could note these guardrails as a variable worth controlling for in the fire drill design.
There was a problem hiding this comment.
Yeah, check with Mike and decide between you two whether you want to combine them or stagger them. Either works for me.
|
|
||
| ### Proactive refactoring | ||
|
|
||
| When AI coding tools like Claude implemnt code, they often struggle to recognize when hard-coded string or small code block is repeated and should be abstracted into its own constant or function. This problem gets worse when the shared code block exists in existing code and new code. Agents also often fail to move code into other files or packages when refactoring. Small, repeatable blocks are a foundation of maintainable code. We should investigate whether we can train an agent to make these sorts of decisions. Claude is clearly capable of refactoring when prompted to. This indicates that implementing a review-time AI agent that recommends sections to refactor could be fairly straightforward. Less straightforward might be to ensure that AI agents contributing code make refactoring decisions without external prompting. |
There was a problem hiding this comment.
I like this.
I think it's also relevant to the idea in docs/problems/architectural-invariants.md on "periodic drift detection".
The idea there is to implement background agents that (unprompted) seek out differences between the architectural docs and the actual code base - and propose adjustments to the code to align with the docs or (in some circumstances not currently defined) propose updates to the architecture to reflect what's in the code.
This kind of "refactor to clean up in a codebase, regardless of broader architecture descriptions" is a similar idea. We'll want this to happen during implementation, but also during code review - and again, asyncronously, unprompted, after code merge.
If you agree, can you cross-link those ideas (so that an agent reading the architectural invariants doc can find its way here and vice versa). Check my other comment first to see if we should decompose this whole doc and move it into some of the other problem docs first, though, to save on re-work.
There was a problem hiding this comment.
Looks like this document will be rolled into #32 but I can make sure to link to docs/problems/architectural-invariants.md when moving things over.
We'll want this to happen during implementation, but also during code review - and again, asyncronously, unprompted, after code merge
If we're refactoring effectively during implementation and code review, do we really need to refactor separately as well?
There was a problem hiding this comment.
If we're refactoring effectively during implementation and code review, do we really need to refactor separately as well?
I would say yes this because during implementation and code review the agents will be hyper focused on solving the task at hand, resolving a bug it is pointed to, or creating a new feature, ..etc so it would be told to not make changes that don't directly serve the purpose of what it set out to do.
So that's where I see the after code merge unprompted refactoring/cleaning being helpful this can be more a broad check that helps keep the code base tidy. This is the things that can hyper focus on refactoring/cleaning as its main goal.
There was a problem hiding this comment.
Yeah, it's analogous to the human behavior today where we reflect periodically on what we've done the last $N time period and ask - did we do that all right? Did we inadvertently incur technical debt we need to clean up?
| Some of the problems described above nebulous. It's difficult to define when a comment is necessary or what makes a variable name useful. This is exactly what's made these problems difficult to solve to begin with. Implementing guardrails for the above problems may require that we opinionate the AI agents used for those guardrails. This would require giving humans the power to disagree with the agents and help along other agents making contributions that may be stuck due to an overly strict review agent. We will likely need to refine the agents over time as they develop a better understanding of the nuance of these issues. Some of these agents may be relegated to making recommendations rather than gating PRs. By breaking the problem spaces down and determining what is and what is not well defined and/or deterministic, we can hopefully maximize the usefulness of agentic linting guardrails. | ||
|
|
||
| ## Open questions | ||
| - Who decides what makes code idiomatic? |
There was a problem hiding this comment.
It should be possible for a repo owner to establish their own idioms in the repo, and the suite of agents should respect those rules. See also #30
|
@14rcole could you check this? I think your input is needed |
1 similar comment
|
@14rcole could you check this? I think your input is needed |
|
@rh-hemartin we have a stale PRs job that will pick this up if noone comes back to this in 30 days. |
4 participants
Describes considerations for maintainable agentic code and limiting human cognitive debt.