Add pipeline output and output mode switch rules

Documented the critical rule to emit objects to the pipeline immediately instead of collecting them in arrays or ArrayLists. Added guidance against using -Detailed/-Simple output mode switches and updated checklists and golden rules to reflect these best practices for memory efficiency, user experience, and pipeline compatibility.

Author: potatoqualitee

CLAUDE.md

@@ -405,6 +405,129 @@ $result = Invoke-DbaQuery @splatQuery -SqlInstance $server
 - **Always prefer parameterized queries** when using T-SQL with dynamic values
 - **Document your choice** when T-SQL is used instead of SMO for non-obvious reasons
 
+### PIPELINE OUTPUT - EMIT OBJECTS IMMEDIATELY
+
+**CRITICAL RULE**: NEVER collect objects in an ArrayList or array and output them at the end. Output objects to the pipeline immediately as they are created.
+
+**Why Immediate Output:**
+- **Memory Efficiency**: Objects are released to the pipeline immediately, not held in memory
+- **User Experience**: Users see results streaming in real-time, not waiting until the end
+- **Pipeline Compatibility**: Enables proper pipeline chaining and early termination (Ctrl+C)
+- **Error Resilience**: Partial results are available even if the command fails partway through
+
+**CORRECT - Output immediately:**
+
+```powershell
+foreach ($instance in $SqlInstance) {
+    $server = Connect-DbaInstance -SqlInstance $instance -SqlCredential $SqlCredential
+
+    foreach ($db in $server.Databases) {
+        # Output each object immediately to the pipeline
+        [PSCustomObject]@{
+            ComputerName = $server.ComputerName
+            InstanceName = $server.ServiceName
+            SqlInstance  = $server.DomainInstanceName
+            Database     = $db.Name
+            Size         = $db.Size
+        }
+    }
+}
+```
+
+**WRONG - Collecting in ArrayList (OLD PATTERN - DO NOT USE):**
+
+```powershell
+# WRONG - This is an outdated anti-pattern
+$results = New-Object System.Collections.ArrayList
+
+foreach ($instance in $SqlInstance) {
+    $server = Connect-DbaInstance -SqlInstance $instance -SqlCredential $SqlCredential
+
+    foreach ($db in $server.Databases) {
+        $null = $results.Add([PSCustomObject]@{
+            ComputerName = $server.ComputerName
+            Database     = $db.Name
+        })
+    }
+}
+
+# WRONG - Holding everything until the end
+$results
+```
+
+**WRONG - Using += with arrays (even worse performance):**
+
+```powershell
+# WRONG - Array concatenation is extremely slow
+$results = @()
+
+foreach ($db in $databases) {
+    $results += [PSCustomObject]@{
+        Name = $db.Name
+    }
+}
+
+$results
+```
+
+**NO -Detailed or -Simple Parameters:**
+
+Do NOT create `-Detailed` or `-Simple` switch parameters that change the output object structure. This is an outdated pattern that creates confusion and breaks pipeline expectations.
+
+```powershell
+# WRONG - Do not create output mode switches
+param(
+    [switch]$Detailed,
+    [switch]$Simple
+)
+
+if ($Detailed) {
+    # Return more properties
+} elseif ($Simple) {
+    # Return fewer properties
+}
+```
+
+Instead, return a consistent object with all relevant properties. Users can select the properties they want with `Select-Object`.
+
+**Proper Pattern for Process Block:**
+
+When using `ValueFromPipeline`, output in the `process` block, not `end`:
+
+```powershell
+function Get-DbaExample {
+    [CmdletBinding()]
+    param (
+        [Parameter(ValueFromPipeline)]
+        [DbaInstanceParameter[]]$SqlInstance,
+        [PSCredential]$SqlCredential
+    )
+
+    process {
+        foreach ($instance in $SqlInstance) {
+            $server = Connect-DbaInstance -SqlInstance $instance -SqlCredential $SqlCredential
+
+            foreach ($item in $server.SomeCollection) {
+                # Output immediately in process block
+                [PSCustomObject]@{
+                    ComputerName = $server.ComputerName
+                    InstanceName = $server.ServiceName
+                    SqlInstance  = $server.DomainInstanceName
+                    Name         = $item.Name
+                }
+            }
+        }
+    }
+}
+```
+
+**Summary:**
+- Output objects immediately as they are created
+- Never use ArrayList, Generic.List, or array += to collect results
+- Never use `-Detailed`/`-Simple` output mode switches
+- Process pipeline input in the `process` block, not `end`
+- Let PowerShell's pipeline handle the collection if the user needs it
+
 ### SPLAT USAGE REQUIREMENT
 
 **USE SPLATS ONLY FOR 3+ PARAMETERS**
@@ -1018,6 +1141,8 @@ This allows you to manually test commands against actual SQL Server instances be
 **dbatools Patterns:**
 - [ ] SMO used first for object manipulation, scripting, and property access
 - [ ] T-SQL only used when appropriate (system views, DMVs, stored procedures, performance, version-specific)
+- [ ] Pipeline output emitted immediately (no ArrayList/array collection)
+- [ ] No `-Detailed`/`-Simple` output mode switches
 - [ ] EnableException handling correctly implemented
 - [ ] Parameter validation follows dbatools pattern
 - [ ] Where-Object conversions applied appropriately
@@ -1049,10 +1174,12 @@ The golden rules for dbatools code:
 2. **NEVER use `= $true` in parameter attributes** - Use modern syntax: `[Parameter(Mandatory)]` not `[Parameter(Mandatory = $true)]`
 3. **NEVER use `::new()` syntax** - Use `New-Object` for PowerShell v3 compatibility
 4. **NEVER be dismissive about SQL Server versions** - Support SQL 2000 when feasible, skip gracefully when not
-5. **ALWAYS prefer SMO first** - Use T-SQL only when SMO doesn't provide functionality or for better performance/UX
-6. **ALWAYS align hashtables** - Equals signs must line up vertically
-7. **ALWAYS preserve comments** - Every comment stays exactly as written
-8. **ALWAYS use double quotes** - SQL Server module standard
-9. **ALWAYS use unique variable names** - Prevent scope collisions
-10. **ALWAYS use descriptive splatnames** - `$splatConnection`, not `$splat`
-11. **ALWAYS register new commands** - Add to both dbatools.psd1 and dbatools.psm1
+5. **NEVER collect pipeline output** - Emit objects immediately, never use ArrayList/array to hold results until the end
+6. **NEVER use `-Detailed`/`-Simple` switches** - Return consistent objects, let users use `Select-Object`
+7. **ALWAYS prefer SMO first** - Use T-SQL only when SMO doesn't provide functionality or for better performance/UX
+8. **ALWAYS align hashtables** - Equals signs must line up vertically
+9. **ALWAYS preserve comments** - Every comment stays exactly as written
+10. **ALWAYS use double quotes** - SQL Server module standard
+11. **ALWAYS use unique variable names** - Prevent scope collisions
+12. **ALWAYS use descriptive splatnames** - `$splatConnection`, not `$splat`
+13. **ALWAYS register new commands** - Add to both dbatools.psd1 and dbatools.psm1