docs: Add contributor guidance problem domain by adambkaplan · Pull Request #7 · fullsend-ai/fullsend

adambkaplan · 2026-03-10T16:33:49Z

Adds a new problem document exploring how to make Konflux contribution rules clear to both human contributors and AI coding assistants.

The core challenge: humans learn contribution norms through mentorship, Slack conversations, and institutional memory, while AI agents (Claude, GitHub Copilot, Cursor) only have access to what's written in the repository. This creates a "verbosity gap" — AI needs all institutional knowledge explicit and written down, but making documentation that verbose can overwhelm human contributors.

The document explores five approaches for bridging this gap, including making implicit knowledge explicit, using verbose CLAUDE.md files for agent-specific context, and layered documentation with progressive disclosure. It emphasizes the "no agent required" principle: using AI must not be required to contribute to Konflux.

arewm · 2026-03-10T17:55:17Z

+What tests need to pass before a PR is mergeable? What's the difference between a CI failure that's a legitimate block vs. a known flaky test?
+
+- Humans can ask: "CI failed but I see this test is flaky — should I retry?" or "How do I run the integration tests locally?"
+- AI assistants need this documented: "Known flaky tests: X, Y, Z — these can be retried. To run integration tests locally: [commands]"


Is this targeting flaky tests in the inner or outer loop? I would imagine that a better consideration would be to remove flaky tests because they likely don't provide a good signal (or at least they provide a confusing one).

Updated to be more general - discuss "how to contribute tests"

arewm · 2026-03-10T17:56:29Z

+
+For exploratory contributions ("I think this might fix the issue but I'm not sure"), what's the low-friction path to get feedback?
+
+- Draft PRs are the GitHub-native answer


Some people use draft PRs to indicate that they haven't looked at the content/changes yet. This breaks down if we are aiming to go fully agentic. What do we see as the intended use case of these?

I think draft prs for agents is an open question. There's also two categories of "draft" that I have observed:

GitHub Drafts which typically don't have CI checks enabled

WIP pull requests that do have CI checks enabled, but otherwise trigger an automation that blocks merge.

I don't even know if "draft" makes sense for a fully agentic flow.

arewm · 2026-03-10T17:57:37Z

+
+This isn't a separate CLAUDE.md for agents vs CONTRIBUTING.md for humans. It's making the existing CONTRIBUTING.md and architecture docs more complete and explicit, so both humans and agents can learn from them.
+
+**Pros:** Single source of truth. Benefits humans too (especially new contributors). No special formats or duplication.


Should this be sources because we are mentioning multiple ones?

Rephrased to "root source of truth"

arewm · 2026-03-10T17:58:22Z

+
+**Pros:** Single source of truth. Benefits humans too (especially new contributors). No special formats or duplication.
+
+**Cons:** Requires discipline to capture institutional knowledge as it emerges. Risk of becoming encyclopedic and overwhelming. Needs curation to stay relevant.


If we are looking at an agent-assisted flow, are there criteria that we can use to suggest whether we need to update any of this documentation to capture contributing guidelines which were not clear?

arewm · 2026-03-10T17:59:54Z

+
+### Approach 3: Layered documentation with progressive disclosure
+
+Not all contributors need to know all rules. Structure guidance by contribution complexity:


Is this structure proposed for specific files?

Updated to specifically reference CONTRIBUTING.md

gbenhaim · 2026-03-10T20:34:17Z

What is the value of an outside contributor when we have a team of agents that write all the code? In this case, what we need is reviewers we can count on, since producing code isn't a challenge anymore.

adambkaplan · 2026-03-10T23:02:07Z

What is the value of an outside contributor when we have a team of agents that write all the code?

This is almost a philosophical question - what does it mean to be an open source contributor when the code is written by bots? Are we all project managers or product owners now?
A cynical take on having human code contributors alongside bots: passionate contributors are cheaper than any agent token budget.
A more charitable take: there will always be an N% of feature requests or bug reports that our current agent prompts + LLMs can't handle. Human intervention will be needed from time to time.

twaugh · 2026-03-11T15:26:53Z

What is the value of an outside contributor when we have a team of agents that write all the code?

This is almost a philosophical question - what does it mean to be an open source contributor when the code is written by bots? Are we all project managers or product owners now?

I submitted another PR tackling some of these topics: #9

Incorporates review feedback from PR fullsend-ai#7 to resolve conflicts with other problem documents and clarify several points. Major changes: 1. Fix conflict with codebase-context.md (arewm, line 88): - Revised Approach 2 to align with ETH Zürich research - Changed from "verbose CLAUDE.md" to "minimal CLAUDE.md with references to CONTRIBUTING.md" - Emphasizes 60-line limit and single source of truth in CONTRIBUTING.md - CLAUDE.md now provides only non-obvious context plus navigation 2. Remove zero trust violation (arewm & ralphbean, line 166): - Deleted exemption for agent-generated PRs - All PRs treated equally regardless of source - Aligns with security-threat-model.md zero trust principle - Simpler implementation, better auditability 3. Add security perspective to "no agent required" (ralphbean, line 197): - New subsection on equal treatment from security perspective - "System shouldn't grant preferential treatment to input simply because it appears to be from an agent" - Reinforces both accessibility AND security principles Minor clarifications: - Line 100: Revise flaky tests - should be fixed/removed, not documented - Line 106: Draft PRs serve same purpose regardless of who opens them - Line 124/126: Grammar fix and documentation feedback loop - Line 149: Clarify layered structure is conceptual, not file-specific All reviewer comments addressed while maintaining document structure presenting multiple viable approaches. Signed-off-by: Adam Kaplan <adkaplan@redhat.com> Assisted-by: Claude <noreply@anthropic.com>

Adds a new problem document exploring how to make Konflux contribution rules clear to both human contributors and AI coding assistants. The core challenge: humans learn contribution norms through mentorship, Slack conversations, and institutional memory, while AI agents (Claude, GitHub Copilot, Cursor) only have access to what's written in the repository. This creates a "verbosity gap" — AI needs all institutional knowledge explicit and written down, but making documentation that verbose can overwhelm human contributors. We must find ways to document code requirements, norms, and "head knowledge" systematically such that they are comprehensible to humans and agents. This is a distinct from the "human factors" problem, which addresses higher philisophical challenges of having agents being the primary code authors in an open source project. It potentially relates to/ overlaps with the "codbebase context" problem, which focuses on how to provide code context to AI agents specifically. The following key principles are set for solving the contributor guidance problem: - AI agents are not required to contribute source code - The system should treat human and agent-authored code equally The document explores five approaches for bridging this gap, including making implicit knowledge explicit, using verbose CLAUDE.md files for agent-specific context, and layered documentation with progressive disclosure. These approaches can be refined in follow-up experiments. Signed-off-by: Adam Kaplan <adkaplan@redhat.com> Assisted-by: Claude <noreply@anthropic.com>

adambkaplan · 2026-03-16T17:34:38Z

@arewm @ralphbean updated to incorporate the broader "human factors" problem and "codebase context" problem - both of which are related. I also cut out a bunch of Claude generated content that was repetitive/overly verbose.

The prescribed "fixes" are now "proposed solutions" that are candidates for future experiments.

Document the end-to-end SDLC pipeline experiment using GitHub Actions as the coordination layer for four AI agents (triage, implementation, review, fix). The repo is the coordinator — no orchestrator agent. Includes: - Pipeline, review agent, fix agent, and context passing diagrams - Pluggable reviewer architecture and identity model - Security layers (Model Armor, token isolation, fail-closed scanning) - Two verified demos: first-pass approval and review/fix loop - Timing data and fix agent telemetry from PR #7 - 13 tracked issues with concise write-ups - 58s demo video and PR timeline screenshot Test repo: nonflux/integration-service (public playground fork) Signed-off-by: Wayne Sun <gsun@redhat.com>

Seven specialized agents for working on the fullsend project: - fullsend-architect (opus): architectural coherence guardian; knows all ADRs, five execution layers, story dependencies, repo-as-coordinator invariant - go-developer (sonnet): CLI specialist; forge abstraction, layered config, multi-role GitHub App model, known gaps in PR #132 - doc-architect (sonnet): problem doc and ADR writer; design-exploration conventions, org-agnostic authoring rules - stage-prompt-designer (opus): designs/reviews stage agent prompts; triage/implement/review/fix constraints, injection surface rules, known failure modes from live operation (Issues #4, #5, #010a) - security-reviewer (opus): applies fullsend threat model; prompt injection, ADR 0017 credential isolation, sandbox integrity, workflow file protection - workflow-engineer (sonnet): GitHub Actions and dispatch layer; label state machine, slash commands, concurrency groups, fixes for Issues #1 #003b #4 #5 #7 #9 #010a - e2e-integrator (opus): full flow tracing; integration gap analysis, demo readiness checklist, sprint prioritization across stories Also adds .claude/AGENTS.md with usage guide and team composition patterns.

adambkaplan requested a review from a team as a code owner March 10, 2026 16:33

ralphbean reviewed Mar 10, 2026

View reviewed changes

Comment thread docs/problems/contributor-guidance.md Outdated

arewm reviewed Mar 10, 2026

View reviewed changes

ralphbean mentioned this pull request Mar 11, 2026

Add human factors problem document #9

Merged

ralphbean mentioned this pull request Mar 11, 2026

Add problem document for strategic risks #13

Open

adambkaplan force-pushed the contributor-guidance-problem branch 3 times, most recently from 0de0dda to 0b9ae7d Compare March 16, 2026 17:22

adambkaplan force-pushed the contributor-guidance-problem branch from 0b9ae7d to bb8a9b4 Compare March 16, 2026 17:32

ralphbean approved these changes Mar 16, 2026

View reviewed changes

Merge branch 'main' into contributor-guidance-problem

d45bc26

ralphbean merged commit 41993a3 into fullsend-ai:main Mar 17, 2026

waynesun09 mentioned this pull request Apr 21, 2026

feat: implement triage agent (Story 3, #126) #279

Merged

6 tasks

waynesun09 mentioned this pull request May 1, 2026

docs: integrate 'Agents of Chaos' findings into security threat model #578

Merged


		For exploratory contributions ("I think this might fix the issue but I'm not sure"), what's the low-friction path to get feedback?

		- Draft PRs are the GitHub-native answer


		This isn't a separate CLAUDE.md for agents vs CONTRIBUTING.md for humans. It's making the existing CONTRIBUTING.md and architecture docs more complete and explicit, so both humans and agents can learn from them.

		Pros: Single source of truth. Benefits humans too (especially new contributors). No special formats or duplication.


		Pros: Single source of truth. Benefits humans too (especially new contributors). No special formats or duplication.

		Cons: Requires discipline to capture institutional knowledge as it emerges. Risk of becoming encyclopedic and overwhelming. Needs curation to stay relevant.


		### Approach 3: Layered documentation with progressive disclosure

		Not all contributors need to know all rules. Structure guidance by contribution complexity:

Conversation

adambkaplan commented Mar 10, 2026

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

gbenhaim commented Mar 10, 2026

Uh oh!

adambkaplan commented Mar 10, 2026

Uh oh!

twaugh commented Mar 11, 2026

Uh oh!

adambkaplan commented Mar 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants