Skip to main content
Version: V2-Next

Collaboration & Disclosure

Collaboration and Readability​

Starting Point​

The amount of AI-generated content feels demotivating to the team — especially sprawling, unclear descriptions and hard-to-understand issues ("slop"). This section aims to bring back more humanity to collaboration, beyond the existing Maturity Levels.

Limiting and Simplifying AI Output​

  • Agent Skills: Agents are constrained more tightly via skills (collected in a project-wide skill repository) and trimmed for readability.
  • Controlled Language (STE): Agents communicate in ASD-STE100 (already mandated in AGENTS.md) — this policy makes that binding project-wide for all AI text output, not just for coding agents.

Base Rule: "Don't be a meat proxy"​

No one should expect others to read AI-generated content that they themselves have not read.

Issues, descriptions, documentation, and chat messages must therefore be at least AI:AMBER before being passed on. An AI:RED draft may be put up for early discussion, but as soon as someone is expected to work on the issue, the higher threshold applies.

Concrete rules for issues:

  • Use AI labels consistently.
  • AI:RED issues are allowed but must be brought to at least AI:AMBER before being passed on.
  • AI:RED issues do not go into sprint planning.
  • Whoever owns an issue must be able to explain it (cf. Understanding Expectations).
  • Principle: AI is a tool that serves the work. The labels make the level of human control visible; they do not restrict the use of AI.

Code Comments​

AI-generated code comments are particularly disruptive because they often add volume instead of information. The following rules apply:

  • Why, not what. A comment explains the intent or reason behind a decision, not what the next line already shows (e.g., // increment counter above counter++). Such comments are removed in review, not tolerated.
  • No prose repetition of names. Comments that merely paraphrase the method or variable name (e.g., // Gets the user by ID above getUserById(id)) are redundant and will be deleted.
  • No meta-comments about the origin. Notes like "// Added this per your request" or "// Fixed as suggested" belong in the commit message or MR description, not in the code.
  • Javadoc/JSDoc stays informative, not decorative. The documentation required by the Java Style Guide or Frontend Style Guide is not a license to repeat parameters and return values in prose. It should document what is not evident from the signature (side effects, invariants, edge cases).
  • Comments are code. They are subject to the same review expectations as the code itself (see Review Expectations). The author is responsible for them; reviewers may flag superfluous AI comments as a finding and require their removal.

Disclosure​

Obligation​

Every merge request must state the maturity level (see Maturity Levels) in the MR template:

### AI Maturity
- [ ] AI:WHITE — Written independently, no significant AI use
- [ ] AI:GREEN — AI-generated, fully reviewed and understood line by line
- [ ] AI:AMBER — AI-generated to a large extent, architecture/design understood, hot spots reviewed

For AI:AMBER, the MR must additionally document:

  • Which parts were reviewed in detail (hot spots)
  • Where Comprehension Debt exists

Purpose​

The maturity-level declaration is not for evaluation or sanctioning, but gives reviewers relevant context. It signals what to pay particular attention to in review — and where AI-typical patterns are more likely. Across all MRs, it also gives stakeholders a quantitative overview of the state of Comprehension Debt.